Scriptube API Keys: Scopes, Rotation, and Revocation

Every Scriptube API key has a scope — read or full — that decides whether it can only fetch results or also submit, retry, and manage billing-affecting actions. Keys live under /api/v1/keys, and the same endpoint set handles creation, rotation, and revocation.

Creating a key

You need an existing API key with full scope to create another one (the dashboard issues your first key before any API call is possible). Your email must be verified first — key creation is blocked on unverified accounts.

curl -X POST https://scriptube.me/api/v1/keys \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-export-script",
    "scope": "read",
    "expires_in_days": 90
  }'

scope is read or full (default read if you omit it), and expires_in_days is optional (1–3650; omit it for a key that doesn't expire). The response is the only time the full secret is shown:

{
  "key": "sk_live_8f2c...a91d",
  "api_key": {
    "id": "a3f1...",
    "name": "nightly-export-script",
    "key_prefix": "sk_live_8f2c",
    "scope": "read",
    "created_at": "2026-10-28T09:00:00Z",
    "expires_at": "2027-01-26T09:00:00Z",
    "last_used_at": null
  }
}

Copy key somewhere safe immediately. Every later call — GET /api/v1/keys, the dashboard's key list — only ever shows key_prefix, never the full value.

Read vs. full: what each scope can do

As a rule: anything that reads results uses read; anything that submits work, spends credits, or changes account state needs full.

That last line surprises people: even listing your own keys requires a full-scope key, because knowing which keys exist is itself sensitive. If you only need a key to pull finished transcripts into a reporting pipeline, mint a read key for that job — if it leaks, nobody can use it to burn credits or register a webhook pointed at an attacker's URL.

Rotating a key

Rotation mints a replacement and revokes the old key in the same request, so there's no window where both or neither are valid:

curl -X POST https://scriptube.me/api/v1/keys/a3f1.../rotate \
  -H "X-API-Key: YOUR_API_KEY"

The response has the same shape as creation — a new key you must capture immediately, and an api_key record with a new key_prefix. The new key keeps the old key's name, scope, and expiry date (not a fresh 90-day clock), so rotating a key doesn't quietly extend its lifetime.

Rotate on a schedule for anything long-lived — a cron job, a workflow-tool credential (see n8n-youtube-transcript-automation for how the n8n credential stores a key), or a partner integration — rather than letting one secret live forever. Rotating means updating one place (wherever that key is stored) immediately after the call returns, since the old key stops working as soon as the new one is minted.

Revoking a key

curl -X DELETE https://scriptube.me/api/v1/keys/a3f1... \
  -H "X-API-Key: YOUR_API_KEY"

Revocation takes effect on the key's next use — there's no grace period. Revoke immediately if a key leaked into a log file, a public repo, or a support ticket; don't wait to rotate it "later."

Never put a key in a URL

Scriptube authenticates every API call with the X-API-Key header, never a query parameter. Keys in URLs end up in server access logs, browser history, proxy logs, and anywhere the URL gets copied — including into a chat message or a bug report. The same applies to webhook secrets: those sign payloads via a header (X-Scriptube-Signature), not a URL token. If you're building the API into a browser-side tool, don't embed a key client-side at all — proxy the call through your own backend.

One key per job, not one key for everything

Nothing stops you from using a single full-scope key everywhere, but it's worth minting a separate key per consumer: one for your nightly export script, one for a workflow tool like n8n, one for a staging environment. GET /api/v1/keys returns each key's last_used_at timestamp, which is far more useful when every key maps to exactly one job — a key that hasn't been used in months is an easy thing to revoke with confidence, where a shared key never looks safe to touch.

Keys and admin impersonation

If a Scriptube admin is impersonating your account for support purposes, every key-management endpoint — create, list, rotate, revoke — is blocked outright for the duration, regardless of which key is calling it. This isn't a scope issue; it's a hard guard so account support sessions can't be used to mint or exfiltrate a credential on your behalf.

Handling key errors

Every API error follows one envelope: {"code": "...", "message": "...", "detail": "..."}. For keys specifically, watch for a plain 404 on an unknown or already-revoked key id, and a 400 if you try to rotate a key that's already expired — create a new one instead, since an expired key can't be extended.

A minimal rotation script

import requests

BASE = "https://scriptube.me/api/v1"
old_key = "sk_live_8f2c...a91d"

resp = requests.post(
    f"{BASE}/keys/a3f1.../rotate",
    headers={"X-API-Key": old_key},
)
resp.raise_for_status()
new_key = resp.json()["key"]
# Store new_key in your secret manager, then stop using old_key.

Run this on whatever cadence your security policy requires. Pair it with youtube-transcript-api-complete-guide if you're setting up the rest of the API from scratch, and with idempotency-key-safe-retries-transcript-api if that same script also submits batches and needs to survive a retry without double-billing.

Full endpoint reference: /docs.