API keys

​

Anatomy of a key

tdao_live_4heb622mfcousggcescrp4d7xlwslr4w
└──┬───┘ └─────────────────┬──────────────┘
prefix 32 base32 characters (~160 bits)

• Prefix tdao_live_ fixed. Helps secret-scanning tools (GitHub, GitLab, git-secrets) detect leaks. Future scopes (“test_”, “preprod_”) may appear; you can ignore those for now.
• Body 32 base32 characters drawn from a CSPRNG. The math says the probability of two keys ever colliding is approximately zero; a UNIQUE index on the hash is the backup guarantee.
• Length 42 characters total.

​

What a key carries

• The organization that minted it (matched against your X-Organization-Id on every request).
• The user who clicked “Generate” (re-checked on every request if they’re deactivated, the key starts failing immediately).
• A label you chose (for your own bookkeeping never sent to the partner-facing surface).

​

Who can mint

​

Lifecycle operations

1

Generate

Click “Generate API key”, give it a label. The raw value is shown once in a modal. Copy it immediately to your secrets store.The web app walks you through four screens. Every state below is a pop-up rendered on the API Access page.1. Hit the “Generate API key” button.

2. Name the key in the “Create API key” pop-up.Pick a label that uniquely identifies this integration (“Production ERP”, “Staging sync”, “Finance reconciliation job”). The label is for your own bookkeeping, your partners never see it.

3. Copy the secret from the reveal pop-up. This is the only time it appears.The next pop-up shows the raw tdao_live_… value plus the Organization ID side-by-side. There is a copy-to-clipboard button on the secret. Copy it now, paste into your secrets manager. Closing this modal without copying means the key is gone, your only option is to revoke it and mint a fresh one.

4. Confirm the copy and the new row in the keys table.Closing the reveal returns you to the keys table. The new row shows the label, the prefix + last-four, the active status badge, and the Rotate / Revoke actions. The raw value never reappears.

2

Use

Send as Authorization: Bearer tdao_live_… on every call. Always pair with X-Organization-Id.

3

Rotate

Click “Rotate” on a key. The old value is revoked atomically and a new value is shown once. Old in-flight requests using the pre-rotation token complete normally; the next request gets 401 invalid_api_key. Update your secrets store before the rotation completes for zero downtime.

4

Revoke

Click “Revoke”. The key becomes inactive immediately. Use this when a key has leaked, when its integration is decommissioned, or when the user who minted it leaves the org.

​

What’s stored

​

When a key stops working

1. Format wrong → 401 missing_or_malformed_authorization. Token doesn’t start with Bearer tdao_live_.
2. Hash not found → 401 invalid_api_key. Includes the never-existed case AND the revoked case.
3. Expired → 401 api_key_expired. Past its expires_at.
4. Wrong org id in the header → 403 organization_mismatch.
5. Org’s account/subscription bad → 403 org_inactive / org_churned / subscription_required.
6. Org’s API access toggle off → 403 api_access_disabled.
7. Minter is no longer active → 403 api_key_creator_revoked.
8. Minter lost the required capability → 403 insufficient_capability.

​

Best practices

• One key per integration. Mint a separate key for each ERP, each CI job, each downstream consumer. When one rotates, the others are unaffected.
• Store in a real secrets manager. Environment files in source control are a leak waiting to happen. Use Vault, AWS Secrets Manager, Doppler, GCP Secret Manager, or your platform’s equivalent.
• Rotate when a maintainer leaves. The user who minted the key is re-checked per request; deactivating them in our system stops the key. But a copy of the secret outside our system doesn’t care. Revoke + re-mint.
• Don’t share via Slack / email. Use the secrets manager’s “share” feature. The raw value should never appear in chat history.
• Watch your logs. Sudden spikes in 401s on /public/v1/* or any 403 organization_mismatch are security signals. Both are visible in our audit logs as well as your own.