/auth.
GitHub OAuth login
GET /auth/github starts the GitHub OAuth authorization-code flow. The client may include redirect_uri, but its origin must exactly match CLIENT_URL; otherwise the backend returns the user to CLIENT_URL.
The backend redirects to GitHub with a random flow state, PKCE challenge, and the user:email OAuth permission. Configure the OAuth App callback URL as <API_BASE_URL>/auth/github/callback. The callback exchanges the code server-side, then redirects to the client with only github_auth=success or github_auth=error. The session itself stays in an HTTP-only cookie and is never included in the redirect URL.
All email and GitHub sign-in paths issue the same Secure, HttpOnly, SameSite=None session cookie when API_BASE_URL uses HTTPS. The cookie is owned by the API host (for example, api.example.com), not the frontend host, and is automatically included only on credentialed API requests.
For a GitHub App user-access-token integration rather than an OAuth App, set GITHUB_OAUTH_SCOPE to an empty value and grant the app’s Email addresses: Read-only user permission in GitHub.
Endpoints
1. Register User
POST /auth/signup
Registers a new user with an email, name, and password. An email verification OTP is generated and sent via Resend.
Request Body
2. Verify Email OTP
POST /auth/verify-email
Validates the 6-digit OTP code sent to the user’s email address. Upon success, marks the email as verified, creates an active session, and sets the HTTP-only session cookie.
Request Body
3. User Login
POST /auth/login
Authenticates an existing user via email and password credentials. Sets an HTTP-only session cookie.
Request Body
4. Forgot Password Request
PATCH /auth/forgot-password
Requests a password reset OTP for a registered account.
Request Body
5. Verify Forgot Password OTP
PATCH /auth/verify-forgot-password
Verifies the password recovery OTP code.
Request Body
6. Reset Password
PATCH /auth/reset-password
Updates the account password for an authenticated session or verified user.
Request Body
7. Get Current Session
GET /auth/session
Retrieves the caller’s active session metadata and user ID from the HTTP-only cookie. When the caller has no active session, it returns 200 with { "authenticated": false }; this is an expected browser state before login, not a missing route.
8. List All Active Sessions
GET /auth/sessions
Returns a list of all active devices and sessions for the authenticated user.
9. Sign Out Current Device
DELETE /auth/logout
Revokes the current session in Redis and clears the session cookie.
10. Sign Out All Devices
DELETE /auth/logout-all
Revokes all active sessions for the user across all browsers and devices.