/v1. Missing, expired or revoked authentication returns 401 unauthorized; an application identity attempting token administration returns 403 owner_token_required. Examples use an owner token in HEXAGON_API_TOKEN and an origin without /v1 in HEXAGON_API_URL. Do not enable shell tracing or record token-bearing responses in public logs.
List metadata
GET /v1/tokens returns 200 and {tokens:[...]}, ordered by creation time descending, without pagination parameters. Each row has id, label, role, expires_at, last_used_at, revoked_at and created_at; optional historical timestamps may be null. The query includes the tenant’s owner and application rows, including expired/revoked entries. Listing does not return plaintext token values or digests.
Create an application token
POST /v1/tokens accepts a strict JSON object:
Success returns 201, with
id, label, role:"application", expires_at, created_at and token. The response has Cache-Control: no-store. The generated token begins hx_app_; the server stores its SHA-256 digest. This response is the retrieval opportunity for its plaintext value; the list endpoint cannot recover it.
Run in a new private directory. These commands create a credential and save its full response to a private file:
Rotate an application token
POST /v1/tokens/{id}/rotate takes no required body and returns 200 with the same fields as creation and Cache-Control: no-store.
404 application_token_not_found; it cannot recover a lost replacement plaintext. The same error covers missing/foreign, owner-role, expired and already revoked targets. On a lost response, use the owner list to inspect/revoke an identified unusable replacement before deliberately issuing another token. Never assume the old token still works because the response was lost. Revocation does not retract a request that has already passed authentication or cancel its Run.
Revoke an application token
DELETE /v1/tokens/{id} returns 200, {id,revoked_at}. This is a JSON response, not 204.
404 application_token_not_found. The row remains available in the metadata list. An authenticated owner cannot use this endpoint to revoke an owner key.
Path IDs are parsed as strings in these routes, not UUID-validated by the route schema; generated application IDs are UUIDs. Malformed creation bodies and unknown properties return 400 invalid_request. Do not rely on the same idempotency behavior for create, rotate and revoke: only revoke naturally tolerates the repeated action here.
Role boundary and verification
Application tokens can use the allowed task routes, including Session creation, Run submission/observation/cancel, artifact download, preview/access creation and revocation, and selected Agent/catalog/connection reads. They cannot administer credentials, decide approvals or reconcile unknown Tool outcomes. The exact route classification is generated in the HTTP inventory; a matching route still enforces ownership, validation and state checks. After installing a replacement credential, verify an allowed read using it, and check that the old credential receives 401 on a new request. Keep owner credentials separate from the application backend’s runtime token and browser clients. Rotation is a credential operation, not an application deployment or a guarantee of zero downtime. Sources: token operations and role allowlist, authentication, route status and headers. The credential contract review exercised current handlers with real PostgreSQL and isolated test identities: creation status and no-store headers, metadata redaction, rotation preserving expiry, old-token rejection, replacement-token acceptance, repeated revoke, invalid input and foreign-tenant denial. Test credentials were removed afterward. This used Fastify injection, not a network proxy/TLS test or a cloud task.Choose recovery by operation
A client should classify creation as successful at
201; it must not treat that status as an unexpected response and create another token. Rotation and revocation retain their 200 responses. Check the exact endpoint contract rather than applying one status to all Token mutations.
Next: identity operations guide, HTTP overview.