v1 overview
v1 overview — the three contexts (auth / oauth / account), base paths and audiences, endpoint group naming, and what may change within v1.
/v1 is the only version in use. This page is the v1 overview: which contexts it has, their base paths and audiences, how endpoint groups are named, and what kinds of change are allowed in this version.
Shared conventions (authentication, request and response formats, rate limits, caching, time and identifiers) are described once in the overview; this page does not repeat them.
Contexts
| Context | Base path | Audience | Main consumers | Page |
|---|---|---|---|---|
auth | {origin}/v1/auth | auth | Account UI, consent UI; third parties reading user info | auth context |
oauth | {issuer} (i.e. {origin}/v1/oauth) | oauth | Third-party authorization and tokens, consent-internal endpoints | oauth context |
account | {origin}/v1/account | account | Account profile | account context |
The three share no data and are not allowed to call each other directly — cross-context collaboration goes through events. That is why tokens do not cross contexts: an auth-audience token cannot read account data, even when the scope looks sufficient.
Group naming
- The group name is the first segment of the path prefix:
/v1/auth/credentials/*belongs tocredentials,/v1/auth/session/*tosession. - A prefix with a single endpoint is not made into a group; the endpoint is listed directly.
- Group names are documentation-only. They are not protocol concepts and never appear in requests or responses.
What may change within v1
| Item | Rule |
|---|---|
| Compatible changes | Allowed: new endpoints, new optional fields, new error code values |
| Breaking changes | Not allowed — they must go to v2 |
| Field semantics | Existing field semantics and required-ness stay unchanged in v1 |
| Retirement | Only after v2 is stable, running in parallel with notice; never switched off abruptly |
What third parties need
| Need | Where |
|---|---|
| Exchange / refresh tokens | token in the oauth context |
| Read user info | userinfo in the auth context |
| Validate tokens | jwks (oauth context) or introspect (confidential clients only) |
| Manage authorized applications | grants in the oauth context |
The remaining endpoints serve the first-party account UI and the consent UI; third-party calls are rejected. The basis for that is in Scopes and audiences.
How the docs are laid out
This version is organised in three layers: context overview → endpoint group → endpoint.
| Layer | Where | What it holds |
|---|---|---|
| Context overview | The first page under auth / oauth / account | Which groups exist, how calls authenticate, which operations need step-up |
| Group page | One page per group | Paths, parameters, responses and rules for every endpoint in that group |
| Endpoint | A section inside the group page | Field-level tables and samples |
Contexts with many groups or very large groups get one more layer (for example Credential management) so a single page never turns into a hundred-row table. For reverse lookup by path, use the Endpoint index.