REST API

Authentication

Base URL, API keys, scopes, auth headers and auth errors.

Read as Markdown

How to make an authenticated call to the REST API.

Base URL for every call:

Auth header on every call:

Header
Authorization: Bearer sk_live_...
  • One version: v1. There is no version header.
  • riffads.com is 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

Terminal
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 Bearer Authorization wins.
  • 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.

EndpointScope
GET /capabilities, GET /capabilities/{id}Read
GET /presets, GET /presets/{id}/templatesRead
POST /estimatesRead
GET /actors, GET /voicesRead
GET /assets, GET /assets/{id}, GET /assets/{id}/downloadRead
GET /credits/balanceRead
GET /generations, GET /generations/{id}, GET /generations/{id}/waitRead
GET /batches/{id}Read
GET /workflows/templates, GET /workflow-runs, GET /workflow-runs/{id}, GET /workflows/{id}/runsRead
GET /webhooksRead
POST /generationsGenerate
POST /uploads, POST /uploads/{assetId}/finalize, POST /uploads/from-urlGenerate
POST /webhooks, DELETE /webhooks/{id}Generate
POST /workflows/{id}/invoke, POST /workflows/templates/{key}/invokeWorkflows
GET /health, GET /health/readyNo 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".

Response: 401
{
  "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
  }
}
CausecodeHTTPRetry
No header, non-Bearer scheme, blank, unknown or revoked keynot_authorized401no
Too many requests on this keyrate_limited429yes
Key lacks the scope this endpoint needsinsufficient_scope403no
Workspace deletedworkspace_unavailable410no
Plan does not include the APIrequired_plan403no
Key check failed on our sideinternal_error500yes

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).

On this page