API keys

This page covers the full lifecycle of a Traceable API key: generation, usage, rotation, and revocation.

Generating a key

1. Log in to app.traceable.digital
2. Navigate to Settings → API Keys
3. Click New Key
4. Enter a name for the key. Use a name that identifies the integration or system this key will be used for (see naming best practices below)
5. Click Create
6. Copy the key value immediately from the confirmation dialog

Key is shown once

The full key value is displayed only at creation time. Once you close the confirmation dialog, the key cannot be retrieved — only its name and last four characters are visible in the portal. If you lose a key, you must rotate it.

Key format

Traceable API keys are opaque tokens with the following characteristics:

• Prefix: trc_live_ for production keys
• Length: 48+ characters total (including prefix)
• Character set: alphanumeric (a–z, 0–9), lowercase only
• Example: trc_live_a8f3k2p9x7m1n4q6r0s5v8w2y4z7b1c3d6e9f2g5h8j1k2

Do not attempt to parse or derive meaning from the key format — it may change. Treat keys as opaque strings.

Including a key in requests

Pass the key as a bearer token in the Authorization HTTP header on every authenticated request:

# curl
curl -X POST https://app.traceable.digital/api/poli/access \
  -H "Authorization: Bearer trc_live_a8f3k2p9x7m1n4q6r0s5v8w2y4z7b1c3d6e9f2g5h8j1k2" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

// JavaScript (Node.js)
const response = await fetch('https://app.traceable.digital/api/poli/access', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TRACEABLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ... }),
});

# Python
import os
import requests

response = requests.post(
    'https://app.traceable.digital/api/poli/access',
    headers={
        'Authorization': f"Bearer {os.environ['TRACEABLE_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={ ... },
)

The Bearer prefix (with a trailing space before the token) is required. Requests with a malformed header will receive a 401 UNAUTHORIZED response.

Key rotation procedure

Rotate keys without downtime by following this sequence:

1. Create a new key in Settings → API Keys → New Key
2. Deploy the new key to all integrations and environments that use the old key
3. Verify that all integrations are operating correctly with the new key (check the last-used timestamp in the portal)
4. Delete the old key from Settings → API Keys → (key name) → Revoke

Completing steps 1–3 before step 4 ensures there is no gap in service. Both keys are valid simultaneously until you delete the old one.

Revoking a key

To revoke a key:

1. Navigate to Settings → API Keys
2. Click the key name you want to revoke
3. Click Revoke Key
4. Confirm the action

Revocation takes effect immediately. Any in-flight requests that were authenticated before revocation will complete, but any new requests using that key will receive:

{
  "error": "Invalid or revoked API key",
  "code": "INVALID_API_KEY",
  "details": {}
}

HTTP status: 401 Unauthorized

There is no grace period after revocation. If you revoke a key that is still in use in a production integration, that integration will begin failing immediately. Always complete rotation before revoking the old key.

Key naming best practices

Name keys by their purpose or system, not by the person who created them. People leave organisations; integrations don't.

Good names	Poor names
poli-integration-prod	john-smith-key
ci-health-check	my-key
erp-dpp-sync-staging	test
customs-portal-nl	key-2024
public-registry-eu	api-key-1

A good name answers the question: "If something breaks at 2am, which system is this key for?"

Rate limits per key

Each API key shares the account-wide rate limit for authenticated endpoints. The current limit is 120 requests per minute per key.

If your integration requires a higher limit, contact support@traceable.digital with details of your use case.

See the Rate Limiting page for full details including response headers and backoff recommendations.