API Keys

API keys authenticate every request to the Talonic REST API. Keys are prefixed with tlnc_, passed via the Authorization: Bearer header, and scoped so each integration gets only the access it needs. Manage them from Settings → API Keys in the app, or programmatically via /v1/account/keys.

Keys are SHA-256 hashed at rest — the full key is only shown once at creation, so copy it immediately. See the API Documentation for the complete endpoint reference the keys unlock.

Each API key is assigned one or more scopes that control what operations it can perform. Scopes follow the principle of least privilege — create a key with only the scopes your integration needs. For example, a read-only dashboard integration only needs the read scope, while an automated ingestion integration needs extract and read.

For best results, create separate API keys for each integration or service that connects to your Talonic workspace. This makes it easy to rotate or revoke a single key without disrupting other integrations. Most teams maintain one key for their ingestion integration, one for their BI dashboard, and one for webhook-based automations.

API keys are SHA-256 hashed at rest, which means the platform never stores the plaintext key after creation. This is a deliberate security measure — even if the database were compromised, the hashed keys cannot be reversed to their original values. When your integration sends a request, the platform hashes the incoming key and compares it against the stored hash. This design follows the same pattern used by GitHub, Stripe, and other major API providers.

• Prefixed with tlnc_ for easy identification in logs and configuration files
• Passed via the Authorization: Bearer header on every API request
• SHA-256 hashed at rest — the full key is only shown once at creation
• Six scopes: extract, read, write, operations, billing, and delivery (defaults: extract/read/write/operations)
• Create separate keys per integration for independent rotation and revocation
• No limit on the number of keys per workspace

Using Your API Key

Once you have created an API key, include it in the Authorization header of every request to the Talonic API. The key is passed as a Bearer token. All API endpoints require authentication — requests without a valid key receive a 401 Unauthorized response. Rate limits are tiered per namespace and metered per calendar day (UTC); every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so your integration can adapt.

curl https://api.talonic.com/v1/documents \
  -H "Authorization: Bearer tlnc_your_api_key_here"

{
  "data": [
    {
      "id": "doc_7f3a1b2c",
      "filename": "invoice.pdf",
      "status": "completed",
      "document_type": "Invoice"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTU2fQ"
  }
}

# List keys (raw values are never returned — only a masked prefix,
# scopes, and usage metadata):
curl https://api.talonic.com/v1/account/keys \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Create a scoped key (requires the write scope; the raw key is
# returned once and never retrievable again):
curl -X POST https://api.talonic.com/v1/account/keys \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "bi-dashboard", "scopes": ["read"] }'

# Revoke a key by ID:
curl -X DELETE https://api.talonic.com/v1/account/keys/<keyId> \
  -H "Authorization: Bearer $TALONIC_API_KEY"

If your API key is compromised, delete it immediately from Settings and create a new one. Because keys are SHA-256 hashed at rest, the platform cannot display the key again after creation — you must generate a fresh key and update all integrations that used the old one. For production environments, store API keys in a secrets manager like AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault rather than in environment files or source code.

A common pattern for enterprise teams is to create three API keys with different scopes: one extract-only key for your ingestion integration, one read-only key for your BI dashboard or monitoring tools, and one write key for administrative automation scripts. This separation ensures that a compromised dashboard key cannot be used to upload documents or modify schemas, and that your ingestion integration key cannot access sensitive configuration endpoints. Rotate each key independently on a regular schedule — monthly rotation is a common best practice for production environments.

curl -I https://api.talonic.com/v1/documents \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response headers include:
# X-RateLimit-Limit: 10000
# X-RateLimit-Remaining: 9898
# X-RateLimit-Reset: 2026-05-08T00:00:00.000Z