HTTP API: tokens
The 3 operations tagged tokens, each with its parameters, its body and what it answers.
List the credentials you can act on
GET /v1/tokens
The credentials this caller may see, newest first.
Narrowed the same way revoking is, so nothing appears here that the caller could not then act on: your own, the ones you issued, and — for an instance administrator — everything. An inventory you can read and not revoke is a worse answer than a short one.
Not paginated, for the reason GET /v1/users gives: an instance's credentials are
bounded by how many somebody issued.
Parameters
format(stringornull, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.fields(stringornull, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.
Responses
200:Collection_Token_. Successful Response422:HTTPValidationError. Validation Error
Issue a credential
POST /v1/tokens
Mint a credential and return it once.
The secret is in this response and in nothing else, ever. Only a hash is stored, so nothing recovers it afterwards — including this instance. Store it when you receive it.
A credential may never grant more than the one that asked for it: wider scopes, a wider set
of projects, a wider set of projects it may write in, an expiry later than its own, or an
unpinned workspace where the caller's own token is pinned are all refused — as is issuing
for somebody else without instance:user_create.
Request body: Create as application/json, required.
Responses
201:IssuedToken. Successful Response422:HTTPValidationError. Validation Error
Revoke a credential
DELETE /v1/tokens/{id_or_prefix}
Stop a credential working, now.
Immediate: revoked_at is checked on every request rather than cached anywhere, so there
is no session to wait out. That is what makes this the answer when a token has leaked.
Idempotent, and it keeps the first revocation time — when a credential stopped being trusted is a fact worth not overwriting, and a caller retrying should not change it. The revoked credential is returned rather than an empty 204 so that a repeat call is distinguishable from a first one.
Addressed by id or by the public prefix, because the prefix is what a listing prints and what somebody has in front of them when a token turns up in a log.
Parameters
id_or_prefix(string, in path, required)
Responses
200:Token. Successful Response422:HTTPValidationError. Validation Error