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

# Authentication

> Authenticate requests with a NanoClip API key.

Send your API key as a bearer token on every API request except public health checks.

```bash theme={null}
curl "https://api.nanoclip.ai/v1/projects/proj_abc123" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"
```

## Keep keys server-side

API keys identify a workspace and should be treated like credentials. Do not ship them in mobile apps, browser clients, or public repositories. Route browser and mobile traffic through your own backend when calling NanoClip.

## Scopes

API keys are workspace-scoped. Endpoints require the matching read or write scope for the resource being accessed.

| Scope                  | Allows                               |
| ---------------------- | ------------------------------------ |
| `projects:read`        | Read project metadata                |
| `projects:write`       | Create projects and complete uploads |
| `transcript:read`      | Read transcript results              |
| `transcript:write`     | Start transcript commands            |
| `vision:read`          | Read vision results                  |
| `vision:write`         | Start vision commands                |
| `retake_removal:read`  | Read retake-removal results          |
| `retake_removal:write` | Start retake-removal commands        |
| `*`                    | All public API operations            |

## Check a key

`GET /v1/me` describes the calling key: its workspace, granted scopes, live rate/upload limits, today's usage, and — when credit billing is enabled — the wallet balance and pricing catalog. It needs only a valid key (no scope required), so use it to confirm a key works and to pre-flight scopes, limits, and balance before uploading.

```bash theme={null}
curl "https://api.nanoclip.ai/v1/me" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"
```

`billing.credit_balance_cents` is `null` (not `0`) when credit billing is disabled for the deployment; `agent_context.balance_note` explains it.

## Common auth failures

| Status             | Cause                                                     |
| ------------------ | --------------------------------------------------------- |
| `401 Unauthorized` | Missing, malformed, inactive, or invalid API key.         |
| `403 Forbidden`    | The key is valid but does not include the required scope. |