Authentication
Base URL, API keys, scopes, auth headers and auth errors.
Read as MarkdownHow to make an authenticated call to the REST API.
Base URL for every call:
Auth header on every call:
Authorization: Bearer sk_live_...- One version:
v1. There is no version header. riffads.comis the marketing site. It does not serve/api/v1.- MCP clients sign in with OAuth, not keys. See MCP setup.
Server side only. The key is a secret, so never call the API from a browser.
Send the key
export RIFFADS_API_KEY="sk_live_..."
curl -s https://app.riffads.com/api/v1/capabilities \
-H "Authorization: Bearer $RIFFADS_API_KEY"x-api-key: sk_live_...also works. When both are sent, a BearerAuthorizationwins.- The scheme is case-insensitive (
bearer,BEARER). A key in a query param is never read. - A missing header, a non-Bearer scheme and an unknown key all get the same 401, byte for byte.
Get a key
Owners and admins make keys on the API keys page:
No API endpoint creates, rotates or lists keys.
- Every paid plan includes the API.
- The prefix is always
sk_live_. There is no test key and no sandbox: every call is real. - The key is shown once and stored as a hash. If you lose it, make a new one.
- A key belongs to the workspace, not to the person who made it. It reaches only that workspace.
- Keys never expire. They work until someone revokes them.
- A name is required, up to 60 characters. Name it after where it runs (
CI pipeline, staging). - A key can carry an optional rolling 24 hour credit budget: Spend limits.
Scopes
Read is on every key: tick Generate or Workflows for more. Scopes can never be widened, so for another scope make a new key.
| Endpoint | Scope |
|---|---|
GET /capabilities, GET /capabilities/{id} | Read |
GET /presets, GET /presets/{id}/templates | Read |
POST /estimates | Read |
GET /actors, GET /voices | Read |
GET /assets, GET /assets/{id}, GET /assets/{id}/download | Read |
GET /credits/balance | Read |
GET /generations, GET /generations/{id}, GET /generations/{id}/wait | Read |
GET /batches/{id} | Read |
GET /workflows/templates, GET /workflow-runs, GET /workflow-runs/{id}, GET /workflows/{id}/runs | Read |
GET /webhooks | Read |
POST /generations | Generate |
POST /uploads, POST /uploads/{assetId}/finalize, POST /uploads/from-url | Generate |
POST /webhooks, DELETE /webhooks/{id} | Generate |
POST /workflows/{id}/invoke, POST /workflows/templates/{key}/invoke | Workflows |
GET /health, GET /health/ready | No key. See Health |
- A Generate key can't invoke a workflow, and a Workflows key can't submit a generation. To do both, tick both.
- A Read-only key can't spend or change anything, so it is safe for dashboards.
Revoke and rotate
- Revoke in the app: the next call with that key gets
401 not_authorized. Work already running still finishes. - To rotate: make the new key, deploy it (both work meanwhile), then revoke the old one.
- There is no cap on keys. One key per integration keeps limits and revocation apart.
- Committed a key to a repo? Revoke it now.
Auth errors
Every failure is wrapped in error. Every 401 also sends WWW-Authenticate: Bearer realm="RiffAds".
{
"error": {
"ok": false,
"code": "not_authorized",
"message": "This RiffAds API key is not valid. Check the Authorization header, or create a new key at app.riffads.com/api-keys.",
"retryable": false,
"credits_charged": 0
}
}| Cause | code | HTTP | Retry |
|---|---|---|---|
| No header, non-Bearer scheme, blank, unknown or revoked key | not_authorized | 401 | no |
| Too many requests on this key | rate_limited | 429 | yes |
| Key lacks the scope this endpoint needs | insufficient_scope | 403 | no |
| Workspace deleted | workspace_unavailable | 410 | no |
| Plan does not include the API | required_plan | 403 | no |
| Key check failed on our side | internal_error | 500 | yes |
Checks run in this order: header, key, scope, workspace, plan. The key check never answers quota_exceeded, because keys made in the app have no request allowance.
Rate limits
Each key has its own limits. Over them you get 429 rate_limited, so wait for Retry-After when it is sent (Limits).