Mint a personal access token.
const url = 'https://example.com/api/v1/api-tokens';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"expires_at":"2026-04-15T12:00:00Z","name":"example","owner_user_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","role":"viewer","scope":"All","surfaces":["mcp"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/api-tokens \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "expires_at": "2026-04-15T12:00:00Z", "name": "example", "owner_user_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "role": "viewer", "scope": "All", "surfaces": [ "mcp" ] }'The raw token is in this response and nowhere else — only its hash is stored, so no later call can produce it again.
The token acts as an account (owner_user_id, defaulting to the caller): disabling or
deleting that account stops the token, and its role is capped at the owner’s current role on
every use. For anything unattended, own it with a service account rather than a person — see
POST /api/v1/users — so the credential does not depend on who happened to create it.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Request body for POST /api/v1/api-tokens.
object
When the token stops working. Omit for no expiry — appropriate for a service account driving an integration, and deliberately still allowed.
Human label (unique, ≤128 chars).
The account the token acts as. Omit to own it yourself; name a service account for anything unattended, so the credential outlives whoever set it up.
The role the token grants (viewer is the right default for a read-only client). Capped at
the owner’s role on every use, so this is a ceiling rather than a promise.
Which surfaces the token may authenticate. Defaults to ["mcp"] when omitted, matching what
every token issued before this field existed can do.
Responses
Section titled “Responses”Token minted; token is the raw bearer and is returned only here
The one and only response carrying a usable token.
A named type rather than an inline json! because of what the token field is: the client has
to store it now, since only its hash is kept and no later call can produce it again. Giving it a
type makes that field visible in one place if this response ever grows a second consumer.
object
Predefined roles, ordered least → most privileged.
The raw bearer token, returned once. Never stored, never logged.
Example
{ "role": "viewer", "surfaces": [ "mcp" ]}Bad name, a scope naming no groups or a group that does not exist, a scope on a token whose owner is itself group-scoped, no surface named, an expiry already in the past, or an owner id that names no account
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}No valid bearer token
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role below Admin
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}An API token with that name already exists
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Skeleton mode has no token store
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}