oauth context overview
The endpoint groups of the v1 oauth context (base path /v1/oauth, i.e. the issuer), and how callers are split.
The oauth context is the authorization server itself: issuing codes, exchanging tokens, revoking, introspecting, publishing keys, and letting users manage the applications they have authorized. It serves both third-party clients and the first-party consent UI.
Base path: {issuer}, i.e. {origin}/v1/oauth. Token audience is oauth.
Endpoint groups
| Group | Endpoints | Caller | Page |
|---|---|---|---|
| Token exchange | POST /token | Third-party clients (server-side) | oauth tokens |
| Revocation | POST /revoke | Clients | Revocation |
| Introspection | POST /introspect | Confidential clients | Introspection |
| Public keys | GET /jwks | Resource servers | Public keys |
| Authorization | POST /preauthorize, POST /authorize | First-party consent UI | Authorization |
| Authorized applications | GET /grants, DELETE /grants/:clientId | First-party console | Authorized applications |
Two kinds of caller
| Caller | Credential | Endpoints it can touch |
|---|---|---|
| Third-party client | Client authentication (client_secret_basic / client_secret_post / none) | token, revoke, introspect, jwks |
| First-party consent UI and console | Identity assertion plus consent ticket, or an oauth-audience resource token | preauthorize, authorize, grants |
The two token families do not inherit from each other
The first-party console holds one auth session. Account data (credentials, sessions, audit) is read directly with an auth resource token; authorization relationships are reached through an RFC 8693 token exchange that yields a short-lived oauth-audience resource token (5 minutes, never persisted, audience trimmed to oauth / account).
A token obtained by exchange cannot reach auth-side scopes, and the reverse is true as well.
Token responses are never cached
token, revoke and introspect all send Cache-Control: no-store. This is not optional hardening:
- a cached token response can be handed to a different requester by an intermediary;
- a revoke response is an empty body, so caching one
200makes later revocations "succeed" while the token is still alive; - a cached introspection result makes revocation ineffective for the duration of the cache.
jwks is the opposite: it explicitly allows caching for 5 minutes.
Related
- Protocol details and parameters: Endpoint reference
- Error codes: Error codes
- Full integration flow: Authorization code flow