API reference overview
How API reference differs from the integration guide, how it is organised by version and context, how to read parameter tables, and what is available today.
API reference answers exact meaning questions: what type this field is, whether it is required, where its boundaries are, what an error looks like. It does not teach you how to integrate — that is the integration guide.
This page explains the split, how the section is organised, and what you can look up today.
How it differs from the integration guide
| What you want to know | Where to go |
|---|---|
| How do I integrate step by step | Integration guide |
| What usually causes this step to fail | Error codes |
| Can this parameter be omitted, what if I pass it wrong | This section |
| What is the value set of this response field | This section |
Where the same subject appears in both, the integration guide describes the flow and this section describes the field. Neither repeats the other's layer.
Organisation
Four levels, narrowing downwards:
| Level | Notes | Where |
|---|---|---|
| Overview | Structure and shared conventions across versions | API overview |
| Version | One independent contract | v1, v2 |
| Context | A bounded context on the server, which is also a token audience | Inside a version |
| Endpoint group | A set of endpoints sharing a path prefix | Inside a context page |
v1's three contexts map one-to-one onto audiences:
| Context | Audience | Contains | Status |
|---|---|---|---|
| auth context | auth | User info reads, identity assertion validation | In progress |
| oauth context | oauth | Tokens, revocation, introspection, grant management, consent-internal endpoints | In progress |
| account context | account | Account profile | In progress |
How to read parameter tables
Every parameter table in this section follows the same conventions:
| Column | Meaning |
|---|---|
| Name | Parameter name, case-sensitive |
| Type | string / integer / boolean / array / object |
| Required | "Yes" means omitting it fails outright; "No" means omitting it has a default behaviour |
| Constraints | Length, value set, format; "none" means no extra restriction |
| Example | Illustrative value, not a contract |
Three rules:
- Required is not sufficient: all parameters present but one value invalid is still a parameter error, and the error code names which one;
- Constraints are hard boundaries: a request outside them is rejected, not handled best-effort;
- Fields not documented do not exist: do not depend on response fields that are not written down here; they may disappear at any time.
What is available today
Shared conventions and the endpoint index are ready; per-resource field docs are being filled in. Unfinished pages are marked "In progress" and list the interfaces they will cover.
When a field is missing, fall back in this order:
- Endpoint index — confirm the endpoint and authentication first;
- Tokens — all token-related fields live there;
- Error codes — the basis for deciding what went wrong.
Most questions are answered by these three pages; what remains is what this section is being filled in with.
Integration guide overview
The four groups inside the integration guide, how the pages depend on each other, the suggested three-stage order, and what the guide does and does not cover.
FAQ overview
The four categories of the FAQ, how to search by symptom and error code, and how it differs from the error code page.