Overview
How the API docs are organised (overview → version → context → endpoint group), the version list, and the request/response conventions shared across versions.
This section documents the external HTTP API. It is organised in four levels — overview → version → context → endpoint group — and this page is the first: the overall structure first, then the conventions that apply to every version.
How it is organised
| Level | Content | Where |
|---|---|---|
| Overview | Structure, version list, shared conventions | This page |
| Version | One independent contract, the /v1 or /v2 in the path | v1, v2 |
| Context | A bounded context on the server, which is also a token audience | The context pages inside a version |
| Endpoint group | A set of endpoints sharing a path prefix | The group tables inside a context page |
The four levels are not a documentation convention but the implementation structure: the version prefix sits on the route root, the context is the next path segment, and the endpoint group the one after. The URL is the table of contents — /v1/oauth/grants maps to "v1 → oauth → grants".
Versions
| Version | Status | Notes |
|---|---|---|
| v1 | In use | The only usable version today; three contexts: auth / oauth / account |
| v2 | Unreleased | Placeholder. New versions exist only for breaking changes; v2 defines no endpoints yet |
Contexts and audiences
| Context | Base path | Audience | Main consumers |
|---|---|---|---|
auth | {origin}/v1/auth | auth | Account UI, consent UI; third parties reading user info |
oauth | {issuer} (i.e. {origin}/v1/oauth) | oauth | Third-party authorization and tokens, consent-internal endpoints |
account | {origin}/v1/account | account | Account profile |
Contexts share no data and tokens do not cross them: an auth-audience token cannot read account data, even when the scope looks sufficient.
Addresses and versioning
- The version lives in the path (
/v1/), not in a header; there is noAccept-Versionnegotiation. - Within a version only compatible changes happen: new endpoints, new optional fields, new error code values. Existing field semantics and required-ness do not change.
- Breaking changes always come with a new version; the old version runs in parallel for a while and is retired with notice. Behaviour never changes silently on the same path.
- Always read endpoint addresses from discovery; do not hardcode domains.
Authentication
| Scenario | Method |
|---|---|
| Resource endpoints (UserInfo, account management) | Authorization: Bearer <access_token> |
Token endpoints (token / revoke / introspect) | Client authentication: client_secret_basic or client_secret_post; public clients send client_id only |
Unsupported authentication methods return 401 outright. There is no "best-effort" fallback — a fallback attempt only disguises an authentication failure as a parameter error.
Request formats
- Token endpoints:
Content-Type: application/x-www-form-urlencoded. - Consent UI and internal endpoints:
Content-Type: application/json,POSTonly. - Resource endpoints:
GETwith no body; write operations use a JSON body.
Response formats
Two coexist, split by endpoint. Clients must parse both:
| Endpoint class | Success response | Error response |
|---|---|---|
Protocol endpoints (token / revoke / introspect) | Flat JSON (access_token, expires_in, …) | RFC 6749 §5.2: { "error": "...", "error_description": "..." } |
| Resource and management endpoints | Flat JSON | Unified envelope: { success, code, message, details?, timestamp } |
The full code list is in Error codes.
Rate limits
- Each endpoint counts independently, alongside a global limit.
- Exceeding a limit returns
429withRetry-After(seconds). - Honour
Retry-After; use randomised backoff in batch scenarios, not fixed-interval retries.
Caching
| Response | Cache header |
|---|---|
| Token endpoints | Cache-Control: no-store — must not be cached |
jwks | Cacheable for 5 minutes; match keys by kid |
| Resource endpoints | User data is never cacheable |
Time and identifiers
- Times are Unix seconds (
auth_time,iat,exp) or ISO 8601 UTC strings (timestamp). - User identity uses
sub: globally stable and unpredictable. Do not key accounts on email or nickname. - Paginated endpoints use cursor or page parameters; see the individual endpoint page.
Where third parties start
- Integration flow: Integration guide;
- Endpoint and authentication quick reference: Endpoint index;
- Token fields: Tokens;
- Deciding what went wrong: Error codes.
Field-level docs are being filled in per version and context; until then, the four pages above cover everything third-party integration needs.