Authentication
Tendral uses bearer tokens for API access. Tokens are scoped to specific resources, may carry an expiration, and support multi-active rotation.
Token format
API keys look like:
Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Tokens are issued per-organization through the Tendral dashboard. We send the plaintext exactly once at issuance time via a 1Password share link — store it immediately in your secrets manager. We never display the plaintext again; if you lose it, rotate (see below).
Tokens are stored on our side as a SHA-256 hash. Revocation and rotation are immediate.
Scopes
A token may be scoped to a subset of resources. The current scope set:
| Scope | Grants |
|---|---|
| tokens:read | GET /v1/partners/stitched/tokens and /tokens/{token} |
| events:read | GET /v1/partners/stitched/events |
| recipients:read | GET /v1/partners/stitched/campaigns/{id}/recipients |
A request to an endpoint outside the token's scopes returns 403 INSUFFICIENT_SCOPE. Tokens with an empty scope array (legacy issuance) carry full read access — re-issue with explicit scopes when you can.
Expiration
Tokens may carry an optional expires_at. Once past, requests return 401 UNAUTHORIZED. Default issuance has no expiration — set one when you want a guaranteed off-ramp (e.g. issuing a 24-hour grace key during rotation).
Rotation — the roll pattern
Tendral supports multiple active tokens per organization (Stripe's roll pattern). To rotate without downtime:
- Issue a new token. Both old and new tokens are now valid.
- Deploy the new token to your services. Production traffic now uses the new token; pending requests on the old token continue to succeed.
- Set
expires_aton the old token to a near-term timestamp (e.g. 24 hours out) so you have a forced cutover. - After the grace window, revoke the old token explicitly — or let the expiration close it.
Same-day rotation is also fine if you accept brief overlap; the only failure mode is a service still configured with the old token after revocation.
Where to store the bearer
- Yes: a dedicated secrets manager (1Password, AWS Secrets Manager, Vault, Doppler).
- Yes: environment variables read at runtime, via your platform's secrets injection.
- No: source code, VCS, or any commit history. If a token leaks, revoke and re-issue immediately.
- No: client-side code (browsers, mobile bundles). Tendral keys are server-only.