5.4.2.4 Tokens
The Tokens domain of access. Sign-in and tokens. access exchanges an Identity Platform sign-in, an Identity-Aware Proxy identity or a service-account assertion for the short-lived token every other system verifies with the keys published here. The token carries the user, the active Organization and its cell only: rights are read by each system from its own copy of memberships and entitlements. It is one API, with its own contract and its own version.
5.4.2.4.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://access.moonitoring.com/tokens/v1 |
tokens/v1/openapi.yaml |
The data model has no entities for this domain yet; its schemas are part of the proposal. Access tokens are not stored. Refresh tokens are kept by access as internal state, as the SHA-256 of their value in a chain (a rotation adds a link, a reuse of a rotated link revokes the chain), and the jti of every client assertion is kept until the assertion expires so that it cannot be replayed; neither is a business entity. The token request follows the OAuth 2.0 token endpoint shape so that standard client libraries work; the grants are ours, except authorization_code with PKCE, which every app but the Account app uses to sign a person in through the Account app, native apps from the browser and web apps from their own server (Signing In from an App). An authorization code is internal state too: the SHA-256 of its value, the app, its redirect, the challenge and the Person, kept for its 60 seconds and deleted once used.
5.4.2.4.2 Operations¶
Every operation names who calls it and the capability it checks (x-moonitoring-audience, x-moonitoring-capability in the contract); every capability is in the catalog of the data model (req 1002, 1006). Lists are paged by cursor, writes that create something carry an Idempotency-Key, errors are Problem Details.
| Operation | Request | Who | Capability |
|---|---|---|---|
| Public keys | GET /jwks |
Anyone | none |
| Issue a token | POST /tokens |
Anyone | none |
| Revoke a refresh token | POST /tokens/revoke |
Organization users, staff or clients | none: any member of the Organization |
| Authorize an app | POST /authorizations |
Organization users | none: any member of the Organization |
| Register as a new person | POST /registrations |
Organization users, staff or clients | none: any member of the Organization |
5.4.2.4.3 Contract v1¶
Proposed version
v1 is a proposal for review: its endpoints, errors and capabilities were designed from the requirements and the flows and are not confirmed. It leaves proposal with its first release; from then on it changes only as described in Every API Is Versioned.