API Reference
HTTP endpoints for the SimpleAuth external auth API.
All endpoints are under /api/external/auth. The JavaScript SDK wraps every endpoint listed here — you only need this page if you're calling the API directly without the SDK.
Authentication
Send your API key via the Authorization: Bearer <key> header or the X-API-Key: <key> header. Endpoints marked public key accept sa_live_…. Endpoints marked secret key require sa_secret_… and must only be called from your backend.
Registration and login
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST | /api/external/auth/register | Public key | Create a new user account. |
POST | /api/external/auth/login | Public key | Sign in and start a session. |
POST | /api/external/auth/logout | Session cookie | End the current session and clear cookies. |
GET | /api/external/auth/me | Session cookie | Get the currently signed-in user. |
OAuth (browser redirect)
The JavaScript SDK exposes getGoogleAuthUrl / signInWithGoogle and getGithubAuthUrl / signInWithGithub so you rarely call these directly.
Google (Authorization Code + PKCE)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET | /api/external/auth/oauth/google/start | Public key (query apiKey or Authorization / X-API-Key) | Starts OAuth: validates redirectUrl, sets short-lived sa_oauth_state cookie, 302 to Google. |
GET | /api/external/auth/oauth/google/callback | (none — Google redirects here) | Exchanges code, creates/links user, sets session cookies, clears sa_oauth_state, 302 to the stored redirectUrl. |
GitHub (Authorization Code)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET | /api/external/auth/oauth/github/start | Public key (query apiKey or Authorization / X-API-Key) | Starts OAuth: validates redirectUrl, sets short-lived sa_oauth_state cookie (scoped to this callback path), 302 to GitHub. |
GET | /api/external/auth/oauth/github/callback | (none — GitHub redirects here) | Exchanges code, loads profile/emails, creates/links user, sets session cookies, clears sa_oauth_state, 302 to the stored redirectUrl. |
GET /oauth/google/start
Query parameters:
| Name | Required | Description |
|---|---|---|
redirectUrl | Yes | Absolute URL on your app where the user should return after sign-in (origin must match allowed origins for the app). |
apiKey | If not sent as header | Same as other routes: sa_live_… public key. |
Response: 302 to Google’s authorize URL. On error: JSON 4xx/5xx with { "error": "…" }.
GET /oauth/google/callback
Query parameters from Google: code, state. The browser must still send the sa_oauth_state cookie set on /start.
Response: 302 to your redirectUrl with Set-Cookie for the external session. On failure, may 302 to redirectUrl?oauth_error=… when the OAuth state row is still valid, or return a minimal HTML error page.
GET /oauth/github/start / GET /oauth/github/callback
Same query-parameter contract as Google (redirectUrl, apiKey or headers). Callback path must receive the sa_oauth_state cookie set on /github/start. See GitHub sign-in for dashboard setup and callback URL.
POST /register
// Request
{ "email": "user@example.com", "password": "s3cureP@ss", "name": "Jane Doe" }
// Response 200
{ "user": { "id": "...", "email": "user@example.com", "name": "Jane Doe", "emailVerified": false, "createdAt": "..." } }POST /login
// Request
{ "email": "user@example.com", "password": "s3cureP@ss" }
// Response 200
{ "user": { "id": "...", "email": "user@example.com", ... } }GET /me
// Response 200
{ "user": { "id": "...", "email": "user@example.com", "name": "Jane Doe", ... } }Password recovery
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST | /api/external/auth/forgot-password | Public key | Send a password reset email. |
POST | /api/external/auth/reset-password | Public key | Complete the reset using the token from the email. |
POST /forgot-password
// Request
{ "email": "user@example.com" }
// Response 200
{ "success": true, "message": "..." }POST /reset-password
// Request
{ "token": "reset-token-from-email", "password": "newP@ssword" }
// Response 200
{ "success": true }Email verification
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST | /api/external/auth/resend-verification | Public key | Send (or resend) the verification email. |
POST | /api/external/auth/verify-email | Public key | Confirm the email using the token from the link. |
POST /verify-email
// Request
{ "token": "verification-token-from-email" }
// Response 200
{ "success": true }Account management
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST | /api/external/auth/delete-account | Session cookie | Permanently delete the current user's account. Requires the user's password in the request body. |
POST /delete-account
// Request
{ "password": "currentP@ssword" }
// Response 200
{ "success": true }Admin endpoints
Secret key required
These endpoints require the secret key (sa_secret_…) and must only be called from your backend. The server SDK wraps all of these.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/external/auth/admin/users | Create a user from your backend. |
GET | /api/external/auth/admin/users/[id] | Get a user by ID (includes bannedUntil). |
DELETE | /api/external/auth/admin/users/[id] | Permanently delete a user. |
POST | /api/external/auth/admin/users/[id]/ban | Ban a user. Body: { "durationMinutes": 60 }. |
POST | /api/external/auth/admin/users/[id]/unban | Remove a ban. |
GET | /api/external/auth/admin/users/[id]/sessions | List a user's active sessions (metadata only). |
DELETE | /api/external/auth/admin/users/[id]/sessions/[sessionId] | Revoke a specific session. |
POST | /api/external/auth/admin/users/[id]/revoke-all-sessions | Revoke all sessions for a user. |
Replace [id] and [sessionId] with actual values at runtime.