Authentication

Snaapi uses Better Auth for authentication, providing email/password login, social OAuth providers, and secure session management out of the box.

Better Auth Integration

Better Auth handles user registration, login, session tokens, and account management. Snaapi extends the base configuration with a registry plugin that adds API key management and resource-level authorization.

All auth-related tables (users, sessions, accounts, verifications) are managed by Better Auth and created automatically on first startup.

Email and Password

Email/password authentication is enabled by default. To disable it, set the environment variable:

ENABLE_EMAIL_PASSWORD_LOGIN=false

When enabled, users can register and log in with an email address and password through Better Auth's built-in endpoints.

You can require email verification before granting access:

REQUIRE_EMAIL_VERIFICATION=true

Snaapi supports OAuth login through Google and GitHub. Configure each provider with its client ID and secret:

Google

AUTH_GOOGLE_CLIENT_ID=your-google-client-id
AUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

GitHub

AUTH_GITHUB_CLIENT_ID=your-github-client-id
AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret

Providers are automatically enabled when their environment variables are set. No additional configuration is required.

Session Management

Better Auth manages sessions via secure cookies with the following defaults:

Setting	Value
Cookie name	`snaapi_auth_session_token`
Prefix	`snaapi_auth_`
HttpOnly	`true`
Secure	`true` (unless development)
SameSite	`Lax`
ID generator	UUID

Trusted Origins

For cross-origin requests, configure allowed origins as a comma-separated list:

SNAAPI_TRUSTED_ORIGINS=https://app.example.com,https://admin.example.com

User Fields

Each user record includes standard Better Auth fields plus two Snaapi-specific fields:

Field	Type	Description
`primaryRole`	string	The role used for authorization decisions
`allowedRoles`	string	JSON-encoded array of roles the user may adopt

The primaryRole defaults to the value of the SNAAPI_DEFAULT_ROLE environment variable (defaults to "user" if not set). See Roles for details on role assignment and behavior.