Auth API

13 endpoints in this group.

GET /api/auth/api-key

Get Api Key

Return the current user's API key metadata. Auto-creates the key if absent.

Responses

POST /api/auth/api-key/rotate

Rotate Api Key

Rotate (regenerate) the current user's API key.

Responses

POST /api/auth/logout

Logout

Clear the auth cookie and revoke the current access-token session.

Best-effort by design: the cookie clear path MUST run even when the presented token is stale or invalid, because the Google-SSO logout loop only manifests for such tokens (a valid token wouldn't be stuck). Therefore we read + decode the cookie inline instead of requiring Depends(get_current_user) — that dependency raises 401 before any clear-cookie statement gets a chance to run.

Bearer clients (mobile sends no cookie) are revoked too: a valid, unexpired Authorization: Bearer access token has its session revoked through the same path as the bp_token cookie, so a logged-out device's token stops working server side. An invalid or expired token (cookie or Bearer) is skipped, never an error: the endpoint always answers 204.

Request body: application/json

Responses

GET /api/auth/me

Me

Return the currently authenticated user's profile.

Responses

GET /api/auth/me/entitlements

Me Entitlements

Return the current user's effective access envelope.

Responses

POST /api/auth/reactivate/confirm

Reactivate Confirm

Request body: application/json

Responses

POST /api/auth/reactivate/request

Reactivate Request

Request body: application/json

Responses

POST /api/auth/refresh

Refresh Token Endpoint

Rotate refresh token and issue a new access+refresh pair.

On first use of a valid token: marks old as used, inserts new token in same family. On reuse of a used token: revokes entire family, returns 401. Feature flag REFRESH_ROTATION_ENABLED=False: issues new access token, same refresh token. When the refresh drops a role-assumption overlay, the response carries assumption_expired: true. When the session window cannot be read the endpoint answers 503 session_unavailable with a Retry-After header and leaves the refresh token unconsumed; clients retry the same request after that delay.

Request body: application/json

Responses

POST /api/auth/register

Register

Create a new public user account in an isolated Free tenant.

Request body: application/json

Responses

GET /api/auth/session

Session Info

Session-clock endpoint for the web app's expiry warning + extend UX.

Returns the access-token expiry, the server's current time (so the client corrects for clock skew when counting down), and the superadmin-tuned warning lead time. Read-only — no DB writes, no side effects. The FE polls this to decide when to show 'session about to expire' and lets the user extend via POST /api/auth/session/extend instead of being logged out silently.

Responses

POST /api/auth/token

Login

OAuth2 password flow. Browser callers receive an httpOnly bp_token cookie; token API callers receive the access token in the body.

If the user has any verified MFA method, returns an mfa-pending token instead of a full access token. The frontend must then call POST /api/auth/mfa/challenge with the code.

Request body: application/x-www-form-urlencoded

Responses

POST /api/auth/verify-phone/confirm

Verify Phone Confirm

Request body: application/json

Responses

POST /api/auth/verify-phone/request

Verify Phone Request

Responses