Token
A token is a short-lived session credential for a principal. You authenticate the sign-in call with an API key, then use the returned token for the duration of the session instead of sending that long-lived key on every request. When the session ends—or sooner if the token might be compromised—revoke it.
Treat tokens like secrets: keep them out of source control, public client bundles, and logs. Prefer tokens (or narrowly scoped keys) for interactive or temporary access; keep privileged API keys in trusted server environments.
Sign in and revoke#
API key + principal → sign in → token + expirationTime → use until expiry → revoke (optional)
- Sign in returns a
tokenandexpirationTime(ISO 8601). Stop using the token after that time. - Revoke invalidates a token early for the same principal. Success is 204 with no body.
Policies still apply: the token acts as that principal, so what it can call depends on the policies attached to it.
When to use these endpoints#
- Issue a session after the caller has a valid API key and a principal id
- Hand temporary access to a service or user without embedding a long-lived key everywhere
- Revoke when logout, rotation, or a suspected leak requires ending the session early