Authentication

Authenticated endpoints take an API key as a bearer token. A key belongs to one organization, carries scopes, and can be rotated without downtime.

Send the key

Authorization: Bearer tk_live_…

A request with no key, a malformed key, or a revoked or expired key gets 401 with code UNAUTHORIZED. The answer is the same in every case, so it says nothing about which keys exist.

Key format and storage

Every key starts with tk_live_ followed by 64 hex characters (256 random bits). You see a key once, when it is issued. Tendral stores only its SHA-256 hash, so a lost key cannot be shown again: ask for a new one and revoke the old.

Scopes

A key is limited to the scopes it was issued with. Each endpoint in the API reference names the scope it needs. A call outside the key's scopes gets 403 with code INSUFFICIENT_SCOPE, and error.details.required_scope names the missing one. Keys issued before scopes existed have every read scope.

Expiry and revocation

A key may carry an expiry time; after it, the key gets 401. Revoking a key takes effect on the next request.

Rotate without downtime

An organization can hold more than one live key, so rotation never needs a gap:

1. Ask for a new key. The old one keeps working.
2. Deploy the new key everywhere you call the API.
3. The old key gets an expiry a short time ahead, so anything you missed fails loudly before it is gone.
4. When the expiry passes, the old key stops working.

Keep keys on the server

• Keep keys in a secrets manager or in environment variables your platform injects at run time.
• Never put a key in source control, a browser bundle or a mobile app.
• If a key leaks, ask for it to be revoked straight away.