Authentication

Prime ships a complete authentication system out of the box. Users can sign in with a password, a magic link, or their Google account. Two-factor authentication and suspicious login detection are included.

Sign in / Sign up

Email and password are the default. Passwords are hashed with Argon2. On signup, users receive a verification email before they can access the app.

Method	Endpoint	Description
POST	/auth	Sign in with email + password
POST	/auth/refresh	Exchange refresh token for a new access token
GET	/auth	Get current authenticated user
DELETE	/auth	Sign out (invalidates the session)

All sign-in endpoints are rate-limited to prevent brute force attacks.

JWT tokens

Authentication uses short-lived access tokens and longer-lived refresh tokens:

TOKEN_SECRET=your_jwt_secret       # Signs access tokens
REFRESH_SECRET=your_refresh_secret # Signs refresh tokens

Generate strong secrets with:

openssl rand -hex 32

Google OAuth

Users can sign in with their Google account. See Google Auth Setup for credentials.

Method	Endpoint	Description
POST	/auth/google	Sign in with a Google ID token
POST	/auth/oauth	Sign in with a generic OAuth provider token ({ token, provider })

Magic Links

Passwordless sign-in via a one-time link emailed to the user. The link expires after MAGIC_LINK_EXPIRY_MINUTES (default: 5 minutes).

Method	Endpoint	Description
POST	/auth/magic	Request a magic link
POST	/auth/magic/verify	Verify the token from the link

Two-Factor Authentication (2FA)

Users can enable TOTP-based 2FA (Google Authenticator, Authy, etc.). Backup codes are generated at setup time.

Sign-in flow with 2FA enabled:

1. User submits email + password → server responds 200 with { "2fa_required": true, "token": "<short-lived jwt>" }
2. User submits their 6-digit OTP together with that token ({ code, jwt }) → server returns tokens

Method	Endpoint	Description
POST	/auth/otp	Submit OTP code during sign-in (body: { code, jwt })

2FA setup, enable/disable, and backup code management are handled through the Users endpoints.

Email Verification

New accounts must verify their email before accessing the app. See Email Verification for TTL and retry configuration.

Method	Endpoint	Description
POST	/auth/verify-email	Verify token from the email link
POST	/auth/resend-verification	Resend the verification email

Password Reset

Method	Endpoint	Description
POST	/auth/password/reset/request	Request a reset email
POST	/auth/password/reset	Submit new password with reset token (body: { email, jwt, password })

The reset token is single-use and expires after a short window.

Suspicious Login Detection

When a user signs in from an unfamiliar device or location, an alert email is sent notifying them of the new sign-in.

Multi-account support

A single user can belong to multiple accounts. After sign-in, the user selects the active account context. The access token encodes the active account and the user can switch without re-authenticating.