Better Auth User Guide
Better Auth User Guide
End-user reference for signing up, signing in, managing sessions, enabling two-factor authentication, and authenticating API requests in the bloqr-backend.
Signing Up
Option A — Angular Sign-Up Page
Navigate to /sign-up in the application. Fill in your name, email, and password, then submit.
The form calls POST /api/auth/sign-up/email and automatically signs you in on success.
Option B — Direct API
curl -X POST https://your-worker.workers.dev/api/auth/sign-up/email \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Smith", "email": "jane@example.com", "password": "a-very-strong-password" }'Success response (200):
{ "user": { "id": "cm9abc123", "name": "Jane Smith", "email": "jane@example.com", "tier": "free", "role": "user", "createdAt": "2025-01-01T00:00:00.000Z" }, "session": { "id": "ses_xyz789", "token": "adblock.session_token_value", "expiresAt": "2025-01-08T00:00:00.000Z" }}The response includes a Set-Cookie: adblock.session_token=... header for browser sessions.
Signing In
Email and Password
sequenceDiagram
participant C as Client
participant W as Worker /api/auth/sign-in/email
participant DB as PostgreSQL (Neon)
C->>W: POST { email, password }
W->>DB: Verify credentials
DB-->>W: user record
W-->>C: 200 { user, session }\nSet-Cookie: adblock.session_token=...
curl -X POST https://your-worker.workers.dev/api/auth/sign-in/email \ -H "Content-Type: application/json" \ -c cookies.txt \ -d '{ "email": "jane@example.com", "password": "a-very-strong-password" }'The -c cookies.txt flag saves the session cookie for subsequent requests.
GitHub OAuth
-
Click Sign in with GitHub on the sign-in page, or redirect to:
GET /api/auth/sign-in/social?provider=github&callbackURL=/dashboard -
GitHub prompts for authorization.
-
GitHub redirects to
/api/auth/callback/githubwith an authorization code. -
Better Auth exchanges the code for a token, upserts the user record, and sets the session cookie. You are redirected to
callbackURL.
# Programmatic OAuth initiation (returns redirect URL)curl -v "https://your-worker.workers.dev/api/auth/sign-in/social?provider=github&callbackURL=/dashboard"# Follow the Location: header to begin the OAuth flowSigning Out
# Browser: clears the session cookiecurl -X POST https://your-worker.workers.dev/api/auth/sign-out \ -H "Content-Type: application/json" \ -b cookies.txtSuccess response (200):
{ "success": true }The adblock.session_token cookie is immediately invalidated and the session record is removed
from the database.
Managing Sessions
Better Auth supports multiple concurrent sessions (e.g., laptop + phone + API client).
List All Active Sessions
curl https://your-worker.workers.dev/api/auth/list-sessions \ -b cookies.txtResponse:
[ { "id": "ses_abc", "userId": "cm9abc123", "createdAt": "2025-01-01T00:00:00.000Z", "expiresAt": "2025-01-08T00:00:00.000Z", "userAgent": "Mozilla/5.0 ...", "ipAddress": "1.2.3.4" }, { "id": "ses_def", "createdAt": "2025-01-03T12:00:00.000Z", "expiresAt": "2025-01-10T12:00:00.000Z", "userAgent": "curl/8.0" }]Revoke a Specific Session
curl -X POST https://your-worker.workers.dev/api/auth/revoke-session \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "sessionId": "ses_def" }'Revoke All Other Sessions
Keeps the current session active and invalidates all others (useful after a password change):
curl -X POST https://your-worker.workers.dev/api/auth/revoke-other-sessions \ -H "Content-Type: application/json" \ -b cookies.txtsequenceDiagram
participant C as Client (current session)
participant W as Worker
participant DB as PostgreSQL
C->>W: POST /api/auth/revoke-other-sessions\nCookie: adblock.session_token=ses_abc
W->>DB: DELETE sessions WHERE userId = me AND id != ses_abc
DB-->>W: deleted count
W-->>C: 200 { success: true }
Two-Factor Authentication (2FA)
Better Auth uses TOTP (Time-based One-Time Password) compatible with apps like Google Authenticator, Authy, and 1Password.
Enable 2FA
Step 1 — Generate a TOTP secret:
curl -X POST https://your-worker.workers.dev/api/auth/two-factor/enable \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "password": "your-current-password" }'Response:
{ "totpURI": "otpauth://totp/bloqr-backend:jane@example.com?secret=JBSWY3DPEHPK3PXP&issuer=bloqr-backend", "backupCodes": ["abc123", "def456", "ghi789", ...]}Step 2 — Scan the QR code (or enter the secret manually) in your authenticator app.
The totpURI can be converted to a QR code by any standard QR library.
Step 3 — Verify the TOTP code to activate 2FA:
curl -X POST https://your-worker.workers.dev/api/auth/two-factor/verify \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "code": "123456" }'2FA is now active. Future sign-ins will require a TOTP code after the password step.
Sign In With 2FA Enabled
sequenceDiagram
participant C as Client
participant W as Worker
C->>W: POST /api/auth/sign-in/email { email, password }
W-->>C: 200 { twoFactorRequired: true, sessionId: "pending_ses" }
C->>W: POST /api/auth/two-factor/verify { code: "123456" }
W-->>C: 200 { user, session }\nSet-Cookie: adblock.session_token=...
Disable 2FA
curl -X POST https://your-worker.workers.dev/api/auth/two-factor/disable \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "password": "your-current-password" }'Password Reset
Step 1 — Request a Reset Email
curl -X POST https://your-worker.workers.dev/api/auth/forget-password \ -H "Content-Type: application/json" \ -d '{ "email": "jane@example.com" }'Better Auth sends an email with a short-lived reset link. The link contains a one-time token.
Step 2 — Submit the New Password
Extract the token from the link (e.g., ?token=abc123) and call:
curl -X POST https://your-worker.workers.dev/api/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "abc123", "newPassword": "my-new-strong-password" }'Success response (200):
{ "success": true }You can now sign in with the new password. All existing sessions are preserved unless you chose to revoke them.
API Authentication (Bearer Token)
For programmatic access without browser cookies, use API keys.
Create an API Key
Sign in first and obtain a session cookie or a short-lived token, then:
curl -X POST https://your-worker.workers.dev/api/keys \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "name": "My CI Pipeline", "scopes": ["compile"], "expiresInDays": 90 }'Response (key shown only once):
{ "id": "key_abc123", "key": "abc_XkYZ1234...", "name": "My CI Pipeline", "scopes": ["compile"], "expiresAt": "2025-04-01T00:00:00.000Z", "prefix": "abc_XkYZ"}Store the key value securely — it is not stored in plain text and cannot be retrieved again.
Use the API Key
Pass the key as a Bearer token in the Authorization header:
curl https://your-worker.workers.dev/api/compile \ -H "Authorization: Bearer abc_XkYZ1234..." \ -H "Content-Type: application/json" \ -d '{ ... }'The Worker detects the abc_ prefix, hashes the key, and verifies it against the database.
List Your API Keys
curl https://your-worker.workers.dev/api/keys \ -b cookies.txtKeys are displayed with their prefix, name, scopes, expiry, and last-used timestamp — never the plaintext value.
Revoke an API Key
curl -X DELETE https://your-worker.workers.dev/api/keys/key_abc123 \ -b cookies.txtThe key is immediately invalidated.
Session Expiry and Renewal
| Setting | Value |
|---|---|
| Session TTL | 7 days |
| Auto-renewal | Refreshed if < 1 day remaining |
| Cookie cache | 5 minutes (reduces DB lookups) |
| Cookie prefix | adblock |
Sessions are automatically renewed on every authenticated request if they are within 24 hours of expiry. No manual token refresh is required.
Related Documentation
- API Authentication — Detailed API key reference
- Better Auth Admin Guide — Admin operations
- Social Providers — GitHub/Google OAuth setup