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.
Create a key
Section titled “Create a key”- Sign in to Clipbeat Studio.
- Open Settings and go to the Developers section.
- Under API keys, choose Create key and give it a name you will recognize later, for example
n8n productionorAgent on my laptop(up to 60 characters). - Copy the key. It is shown only once.
Keys look like this:
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
Section titled “Use a key”Send the key in the Authorization header with the Bearer scheme on every request:
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/1.1 401 UnauthorizedWWW-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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 [email protected] if you see spending you do not recognize.