Manage API Keys

Manage Talonic API keys programmatically: list masked keys, mint a new scoped key (the raw secret is returned once), and revoke keys you no longer need.

The API key management endpoints let a workspace manage its own Talonic API keys programmatically: list your keys (always masked, the raw secret is never returned again), mint a new key with a name and a chosen scope set, and revoke a key you no longer need. The raw secret of a new key is returned exactly once, on creation; store it immediately.

A key carries a subset of the valid scopes: extract, read, write, operations, billing, delivery, usage, records_write. If you omit scopes on create, the key defaults to extract, read, write, operations. Revocation is scoped to your own workspace; revoking a key that belongs to another organization is impossible and returns 404.

Two scopes are attenuation-only. usage gates the cost-visibility routes (GET /v1/usage/pipelines/:id, GET /v1/usage/runs/:id), and records_write is reserved for record-set write routes. records_write is deliberately its own token rather than part of write: a key that holds only write never reaches a record-set write. Self-issuance through POST /v1/account/keys can mint either scope only when the calling key already carries it; otherwise the request fails with 403 scope_not_grantable. A key can narrow its own privilege on a new key, never widen it. Workspace owners grant these scopes de novo through key management in the app.

curl -X POST https://api.talonic.com/v1/account/keys \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline", "scopes": ["extract", "read"] }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "ci-pipeline",
  "key": "tlnc_0123456789abcdef0123456789abcdef",
  "masked_prefix": "tlnc_a1b2c3...",
  "scopes": ["extract", "read"],
  "created_at": "2026-07-01T10:00:00.000Z",
  "expires_at": null,
  "warning": "Store this key now. It will not be shown again."
}