# Authentication

> Create, use, store and revoke Clipbeat API keys, and the scopes each key carries.

Source: https://docs.clipbeat.app/authentication/

The REST API and the MCP server authenticate with a **personal API key**. A key acts as the Clipbeat account that
created it: it reads that account's songs and videos and spends that account's credits.

> **Tip:**
MCP clients will also be able to connect with a one click sign-in (OAuth) instead of a key. That is
**available soon**; see [MCP authentication](https://docs.clipbeat.app/mcp/authentication/). The REST API keeps using API keys.

## Create a key

1. Sign in to [Clipbeat Studio](https://studio.clipbeat.app).
2. Open **Settings** and go to the **Developers** section.
3. Under **API keys**, choose **Create key** and give it a name you will recognize later, for example
   `n8n production` or `Agent on my laptop` (up to 60 characters).
4. Copy the key. It is shown **only once**.

Keys look like this:

```text
cb_live_3q2Xr8...   (cb_live_ followed by 43 random characters)
```

An account can have up to **5 active keys** at a time. Revoke one to create another.

## Use a key

Send the key in the `Authorization` header with the `Bearer` scheme on every request:

```bash
curl -s https://api.clipbeat.app/v1/balance \
  -H "Authorization: Bearer $CLIPBEAT_API_KEY"
```

The same header works for the MCP server at `https://api.clipbeat.app/mcp`. All traffic is HTTPS only.

If the key is missing, malformed, revoked, or belongs to a deleted account, the API answers `401`:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="clipbeat"
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Send a Clipbeat API key: Authorization: Bearer cb_live_... (create one in Clipbeat Studio settings)."
}
```

`GET /v1/openapi.json` is the only endpoint that works without a key.

## Scopes

Every key carries four scopes today. Each endpoint and MCP tool checks one of them; a key without the scope gets
`403 insufficient_scope`.

| Scope | REST endpoints | MCP tools |
| --- | --- | --- |
| `songs:write` | `POST /v1/songs` | `create_video_from_song_url` with `song_url` |
| `videos:write` | `POST /v1/videos` | `create_video_from_song_url` |
| `videos:read` | `GET /v1/songs/{id}`, `GET /v1/videos`, `GET /v1/videos/{id}` | `get_video_status`, `list_my_videos` |
| `account:read` | `GET /v1/pricing`, `GET /v1/balance` | `get_pricing`, `get_balance` |

## Store keys safely

A key can spend the account's credits, so treat it like a password.

- Keep it in an environment variable or a secret manager, never in source code or a public repository.
- Do not put it in a browser, a mobile app or any other client that end users can inspect. Call Clipbeat from your
  server.
- Use one key per integration or machine. If one leaks you revoke only that one.
- Clipbeat stores only a hash of the key and its first characters (shown in Studio as the key prefix), so a lost key
  cannot be shown again. Create a new one.

## See when a key was used

The **API keys** list in Studio shows each key's name, prefix, creation date and when it was last used. Last used is
updated at most once a minute.

## Revoke a key

In **Settings**, **Developers**, **API keys**, choose **Revoke** next to the key and confirm. Revocation is immediate:
the next request with that key gets `401`. Revoked keys cannot be restored.

If you think a key has leaked, revoke it first, then create a new one and write to
[hello@clipbeat.app](mailto:hello@clipbeat.app?subject=API%20key%20leak) if you see spending you do not recognize.
