Authentication

Use a CaptionCraft API key to authenticate server-side requests.

Your API key

Authenticate requests with your CaptionCraft API key.

Keys begin with cc_. Store the key in a secret manager or a server environment variable named CAPTIONCRAFT_API_KEY.

Send a Bearer token

Authorization: Bearer <YOUR_CAPTIONCRAFT_API_KEY>

Every endpoint except List presets, /health, and /openapi.json requires authentication.

Use the endpoint provided with your API key.

export CAPTIONCRAFT_API_URL="https://api.captioncraft.studio"
# Set CAPTIONCRAFT_API_KEY securely in your environment.

curl --fail-with-body "$CAPTIONCRAFT_API_URL/v1/usage" \
  -H "Authorization: Bearer $CAPTIONCRAFT_API_KEY"

Key scopes

Scope	Operations
subtitles:write	Create and cancel jobs
jobs:read	Read job status and result URLs
usage:read	Read prepaid balances and concurrency

Keys are associated with an account. Job access and idempotency are scoped to that account. A key may be restricted by scope, expire, or be revoked.

Keep keys on your server. Do not put them in frontend code, public repositories, URLs, or a NEXT_PUBLIC_ variable. Media download URLs also grant access to the files; treat them as private.

Authentication errors

• 401 UNAUTHORIZED: the key is missing, malformed, expired, or revoked.
• 403 FORBIDDEN: the key lacks the required scope or the account is disabled.

See Errors for the response format and retry guidance.