Authentication

Every request carries an API key as a Bearer token.

Examples use VIDEO_ID and clp_live_... as placeholders.

Send your key

Put the key in the Authorization header of each request, as Authorization: Bearer clp_live_.... Keys start with clp_live_. This call is a good first check, because reading your usage doesn't use any of your monthly limit. The published API spec is the one route that needs no key.

curl -X GET "https://clypso-eta.vercel.app/v1/usage" \
  -H "Authorization: Bearer clp_live_..."

Create a key

Create keys at API Keys. The full value is shown once, when you create it. After that you can only see its prefix, so a lost key can't be recovered. Create a new one instead.

All keys on your account share one monthly limit, and each key has its own rate limit.

Keep keys on your server. A key in a browser or a public repository lets anyone spend your limit.

Revoke a key

Revoke a key at API Keys. Every request checks the key again, so the next request using a revoked key is rejected.

To replace a key without downtime, create the new one, switch your code over, then revoke the old one.

When a key is rejected

A missing or malformed header, an unknown key and a revoked key all get the same 401 with the code invalid_api_key:

JSON

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or missing API key",
    "request_id": "REQUEST_ID",
    "doc_url": "DOC_URL"
  }
}

Build against error.code, since a message can change. See Errors for every code.