> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captioncraft.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={"system"}
Authorization: Bearer <YOUR_CAPTIONCRAFT_API_KEY>
```

Every endpoint except [List presets](/api-reference/list-presets), `/health`, and `/openapi.json` requires authentication.

<Note>
  Use the endpoint provided with your API key.
</Note>

```bash theme={"system"}
export CAPTIONCRAFT_API_URL="https://api.captioncraft.studio"
# Set CAPTIONCRAFT_API_KEY securely in your environment.
```

```bash theme={"system"}
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.

<Warning>
  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.
</Warning>

## 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](/errors) for the response format and retry guidance.