Authentication
Authenticate public API requests with a scoped developer API key.
External /v1 requests require a developer API key from an active paid account. Send it with Authorization: Bearer or X-API-Key. Browser cookies, session bearer tokens, and guest tokens alone cannot authenticate external API requests.
The Transcript website uses the same /v1 workflows through its own server proxy, which authenticates Web requests separately. This does not require a developer key for website users. Guest allowance queries are Web-only and are not available to API keys.
Send the key
Bearer authentication is recommended:
Authorization: Bearer tr_your_api_keyThe equivalent header is also accepted:
X-API-Key: tr_your_api_keyUse one method per request. Never put a key in a query string.
Scopes
API keys are scoped to the operations they may perform.
| Scope | Required for |
|---|---|
transcripts | Transcript extraction, cached retrieval, transcript job polling, the SSE job stream, transcript download/related/delete, and GET /v1/youtube/captions. |
batches | Creating batches, checking batch status, retrying failed items, and exporting results. |
GET /v1/transcript/info, GET /v1/usage, and the five YouTube discovery endpoints (search, videos, channels, channels/{id}/videos, playlists/{id}/items) require a valid key but no additional operation scope. GET /v1/youtube/captions is the exception: it produces a transcript, so it requires the transcripts scope.
When a valid key lacks a required scope, the API returns 403. A missing, malformed, revoked, or expired credential returns 401.
Plan requirement
Creating a developer API key requires an active paid account, and using an API key on /v1 also requires the owning account to be on a paid plan. A key owned by an ineligible account receives 402 with the UPGRADE_REQUIRED code and an action URL. Website users retain their account allowances through the authenticated Web proxy; a session cookie alone does not grant direct API access.
Key handling
- Store keys in a server-side secret manager or environment variable.
- Do not embed keys in browser JavaScript, mobile bundles, logs, or URLs.
- Give each integration its own key and only the scopes it needs.
- Revoke and replace a key immediately if it is exposed.
- Treat the full value as a password; only its prefix and metadata remain visible after creation.