Authentication

Every request to /v1 except GET /v1/formats needs an API key, sent as a bearer token:

curl https://api.cinevva.com/v1/account \
  -H "Authorization: Bearer ck_live_a1b2c3d4..."

There is no query-parameter form. Keys in URLs end up in server logs, browser history, and referrer headers, so the header is the only way to send one.

You also need a subscription

A key proves who you are; a Standard or Pro subscription is what grants access. On a free account a key authenticates correctly and then every call returns 402 with code subscription_required. This applies to all /v1 routes, including the free ones.

Check with GET /v1/account; manage plans at cinevva.com/pricing.

Creating and revoking keys

Manage keys on the API keys page. You can hold up to 10 active keys at a time, which is enough to give each environment or service its own.

A key's secret is displayed exactly once, when you create it. We store only a SHA-256 hash, so we cannot show it to you again or recover it on request. If a key is lost or exposed, revoke it and create a replacement.

Revocation takes effect immediately. Any request using a revoked key gets a 401 with code unauthorized, so revoke first and rotate second if you suspect a leak.

Key format

ck_live_a1b2c3d4e5f6...

The ck_live_ prefix marks a live key that spends real credits. The dashboard shows the first 8 characters after the prefix so you can identify which key is which without holding the secret.

What a key can do

A key acts as your account for rigging: it can create rigs, read the rigs it created, list animations, and read your account status. It draws on the same credit balance as the web tool.

A key deliberately cannot manage other keys. Key creation and revocation require a signed-in browser session, so a leaked key cannot be used to mint more keys or lock you out of your own account.

Keeping keys safe

Treat a key like a password. Concretely:

Keep keys server-side. A key shipped in a web page, a mobile binary, or a game build is public the moment it ships, and anyone who extracts it can spend your credits. If you need to rig from a client application, proxy the call through your own backend.

Use a separate key per environment and per service, so revoking a compromised one doesn't take down everything else. The last_used_at timestamp on the keys page tells you which keys are actually live and which you can safely retire.

Keep keys out of source control. Environment variables or a secrets manager are the right home; a committed key stays in git history even after you delete the line.

Errors

Status	Code	Meaning
401	unauthorized	Missing, malformed, revoked, or unknown key
402	subscription_required	Valid key, no active Standard or Pro plan
402	insufficient_credits	Key is valid, balance will not cover the work
429	rate_limited	Valid key, over the per-minute request limit

A 401 is deliberately identical whether the key never existed or was revoked, so the endpoint cannot be used to probe for valid keys.