Authentication and keys
Key format, scopes, lifetime, rotation, revocation and what keys can never do.
Presenting a key#
Send Authorization: Bearer tt_... or X-TuneToys-Key: tt_.... A key combined with a cookie, a second key header or any other Authorization value is rejected with 400 MIXED_AUTH.
| Property | Behavior |
|---|---|
| Format | tt_<prefix>_<secret>: 8 base32 characters, then 43 base64url characters of random bytes and a 6-character CRC32 checksum. The checksum rejects typos without a lookup. |
| Storage | Only an HMAC of the key is stored. A lost key cannot be recovered; create a new one. |
| Lifetime | 30, 90 (default) or 365 days. There are no non-expiring keys. |
| Rotation | Issues a replacement with the same scopes. The old key keeps working for an overlap (default 24 hours, at most 7 days). |
| Revocation | Immediate on this instance; other instances drop cached keys within 30 seconds. POST /v1/developer/key/revoke lets a leaked key revoke itself. |
| Network | Optional allowlist of up to 16 CIDR ranges (403 KEY_NETWORK). |
| Acting user | The key's creator. Normal owner and visibility checks still apply; scopes never widen them. |
Scopes#
| Scope | Allows |
|---|---|
read:public | Catalog, listings, releases and release bytes |
read:library | Library, bookmarks and sync |
write:library | Bookmark, annotate and remove library items |
read:projects | Your draft projects |
write:projects | Create drafts, save, apply revision-checked operation batches and fork. Never publishes. |
read:products | Your publishers' products and listings; needed for product webhooks |
write:listings | Listing draft fields, assets, documents and translations. Never publishes or changes visibility |
read:usage | Your app's own usage |
read:notifications | Reserved for notification inbox reads |
publish:releases | Create versions, upload artifacts and publish releases for your publisher; the only way to register signed or notarized artifacts |
What keys cannot do#
Keys never reach billing, native device authorization, account authentication, developer app and key management, moderation, publication, visibility changes, storefront publication or server agent proposals. These routes do not list key in their auth modes, so the refusal is structural: 403 AUTH_MODE. Publication, billing and moderation always remain signed-in human actions.
Key requests skip browser Origin, CSRF and X-TuneToys-Request checks because they carry no ambient credential. Bodies must still be application/json, and routes that require idempotency need an Idempotency-Key. The API sends no CORS headers for /v1; call it from a server, not from a web page.