auth context overview
Endpoint groups, authentication and step-up rules of the v1 auth context (base path /v1/auth, audience auth).
The auth context is about "who you are and which session you are in": sign-in and registration, verification challenges, sessions, credential management, user info. Its token audience is auth.
Base path: {origin}/v1/auth. Each group has its own page; see the table below.
Endpoint groups
| Group | Endpoints | Step-up | Page |
|---|---|---|---|
| Sign-in and registration | POST /login, POST /register | None (Turnstile) | Sign-in and registration |
| Verification challenges | POST /verify/email, /verify/email/confirm, /verify/password, /verify/passkey, /verify/passkey/confirm, /verify/authenticator, /verify/recovery-code | None (flow token) | Verification challenges |
| Tokens | POST /token, POST /token/refresh, POST /token/revoke | None | Tokens |
| Sessions | GET /session, GET /session/list, DELETE /session/others, DELETE /session/:sid | Writes need max_age=300 | Sessions |
| User info | GET /userinfo | Resource token, not a session | User info |
| Identity assertion | POST /assertion | None (session token) | Identity assertion |
| Profile | PATCH /profile, PUT /username, GET /username/available | Username change needs max_age=300 | Profile |
| Credential management | /credentials, /providers, /credentials/providers and the per-type endpoints | Add and remove need max_age=300 | Credential management |
| Session elevation | POST /elevation, POST /elevation/complete | The entry point itself is not elevated | Session elevation |
| Password reset | POST /password-reset, POST /password-reset/complete | None (anonymous) | Password reset |
| Third-party callback | POST /provider/:provider/callback | None | Third-party callback |
| Management return | POST /manage/context | None (session token) | Management return |
| Audit | GET /audit-logs | None (session token) | Audit |
Third parties use exactly one endpoint
In this context a third-party integrator has a single endpoint: GET /userinfo, and it requires an auth-audience resource token.
Token exchange, refresh and revocation are not here; they live in token under the oauth context. Everything else serves the first-party account UI and the consent UI.
Authentication matrix
| Endpoint class | Credential |
|---|---|
| Sign-in, registration, verification challenges, password reset, third-party callback | No token; request context, Turnstile and rate limits |
| Sessions, profile, credentials, management return, audit | Session token: Authorization: Bearer <access_token>, audience auth |
userinfo | Resource token, audience auth, scope with at least one of openid / profile / email |
| Elevation step two | Flow token (JWE) in the Bearer header |
Session tokens and resource tokens are not interchangeable
A session token is issued by /v1/auth/token and is bound to no client_id. A resource token is issued by /v1/oauth/token and carries aud and scope.
Using a resource token on session endpoints is rejected, and the reverse is true as well.
Step-up
Destructive operations require "an identity verification completed within the last 5 minutes", i.e. RFC 9470 max_age. When that is not satisfied the response is 401 with a WWW-Authenticate challenge, and the client runs Session elevation.
Error shape
Resource endpoints return the unified envelope { success, code, message, details?, timestamp }. How to tell the three causes of 401 apart (wrong audience, insufficient scope, invalid token) is in Error codes.