Authentication
The Talonic API uses Bearer token authentication. Include your API key in the Authorization header of every request to access endpoints.
API key format
Every Talonic API key starts with tlnc_ followed by 32 random hex characters. The full secret is shown exactly once, when the key is created; listings only show its first characters. Store your key securely and never expose it in client-side code. Keys belong to a single workspace and are limited by the scopes they carry.
Scopes
Each key carries a set of scopes. Keys created without an explicit list get extract, read, write and operations, the same default as keys created in the dashboard. Valid scopes:
| Scope | Notes |
|---|---|
| extract | Default. |
| read | Default. |
| write | Default. Also required to call POST /v1/account/keys. |
| operations | Default. |
| billing | Opt-in. |
| delivery | Opt-in. |
| usage | Cost visibility: GET /v1/usage/pipelines/:id and /v1/usage/runs/:id. Attenuation only. |
| records_write | Writes to record sets. Not implied by write. Attenuation only. |
Attenuation only means a key can pass the scope on to a new key only if it already holds it. Requesting usage or records_write from a key without it returns 403 scope_not_grantable.
Creating keys with the API
POST /v1/account/keys mints a new key from an existing one that holds the write scope. The body takes a name (1 to 255 characters) and an optional scopes array; the raw secret is returned once in the response. See the Account API to list and revoke keys.
curl -X POST https://api.talonic.com/v1/account/keys \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "nightly-export", "scopes": ["read"]}'Making authenticated requests
Pass your API key as a Bearer token in the Authorization header. The base URL for all API requests is https://api.talonic.com.
curl https://api.talonic.com/v1/documents \
-H "Authorization: Bearer $TALONIC_API_KEY"Error responses
If authentication fails, the API returns one of these status codes. See the full error reference for details.
| Status | Meaning | Common Cause |
|---|---|---|
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | Key lacks permission for this resource |
Security best practices
Store API keys in environment variables, not in source code. Use separate keys for development and production, and give each integration only the scopes it needs. Rotate keys every 90 days and revoke any key you suspect is exposed. See rate limits for usage limits per key.
OAuth 2.1 for agents and apps
Clients that act on behalf of a user, such as MCP clients and installed apps, can use OAuth 2.1 instead of a static key. Metadata is published at https://api.talonic.com/.well-known/oauth-authorization-server, and clients can register themselves with dynamic client registration (RFC 7591) at POST /oauth/register.
| Item | Value |
|---|---|
| Grant types | authorization_code, refresh_token |
| PKCE | Required, S256 only (public clients, no client secret) |
| Endpoints | /oauth/authorize, /oauth/token, /oauth/revoke, /oauth/userinfo |
| Lifetimes | Access token 1 hour, refresh token 30 days (rotated on every use), authorization code 10 minutes |
Scopes: extract:write, documents:read, schemas:read, sources:read, webhooks:manage, apps:read, apps:operate, records:write, apps:decide and identity:read. A client that omits scope gets the first five. Tokens carry the user's role, and a tier claim when the granted scopes reach Apps.
An app install can pre-consent apps:read, apps:operate, records:write and identity:read for the workspace. apps:decide can never be pre-consented: the user approves it in person every time. Each decision is also checked against the user's live workspace membership, which must be Senior Member or higher. Otherwise the call is refused with reason decide_grant_required (no active membership) or insufficient_tier (role too low).