Skip to content

Authentication

View as Markdown

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.

  1. Sign in to Clipbeat Studio.
  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:

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.

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

Terminal window
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 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.

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

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.

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.

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 if you see spending you do not recognize.