API keys and scopes
Every account mints its own keys, one per integration, and each key only opens the scopes you tick.
Creating a key
- 1
Open Settings → API keys
The page lists every key on the account.
- 2
Name it after where it will run
The name is only for you, e.g.
n8n production. One key per integration means revoking one never takes down the others. - 3
Tick only the scopes you need
Write scopes do not imply read. A script that lists and creates videos needs both
videos:readandvideos:write. - 4
Copy the key immediately
Only a hash is stored, so the full string appears once and cannot be retrieved. Lost it? Revoke and create a new one.
Keys look like viai_sk_ followed by 43 random characters. The fixed prefix lets GitHub and GitLab secret scanners spot a key accidentally pushed to a repo.
You can set an expiry at creation time. Leave it empty for a key that never expires — it can still be revoked at any moment. An account holds at most 20 active keys.
Sending the key
X-Api-Key: viai_sk_...
Libraries that only speak bearer auth can use this instead — both are accepted:
Authorization: Bearer viai_sk_...
An API key is not a web session
Keys only open paths under /api/v1/public. Sending a key to a web-app endpoint is rejected, and a login cookie cannot call the public API.
Scope reference
| Scope | Opens |
|---|---|
videos:read | List and read videos |
videos:write | Create, render and cancel videos |
jobs:read | Read generation job status |
jobs:write | Queue a generation job |
posts:write | Publish a rendered video to a real channel — kept separate from videos:write because this is the step that goes public |
channels:read | List connected channels |
credits:read | Read the credit balance and transaction history |
campaigns:read | Read campaigns and their slots |
campaigns:write | Create, launch, pause and cancel campaigns |
sources:read | Read news sources and scanned items |
sources:write | Create, update and delete news sources |
media:read | List and read media files |
media:write | Upload and delete media files |
templates:read | List brand templates |
catalog:read | Voices, music, ad templates and AI effects |
analytics:read | Read performance stats |
usage:read | Read API and MCP call history |
Keeping keys safe
- A key opens exactly what you ticked, on your account. Whoever holds the string can do that much — including spending credits.
- Keep keys in environment variables. Never embed one in source code or in a page that runs in an end user's browser.
- One key per integration. The list page shows last used for each key, so a key that has gone quiet is a good candidate for revocation.
- Revocation takes effect immediately and cannot be undone. Suspect a leak? Revoke first.
Authentication errors
| Status | Means | Fix |
|---|---|---|
| 401 | No key sent, or the key is wrong, revoked or expired | Check the header and the key status on the management page |
| 403 | Valid key, missing scope for this path | The body names the missing scope; create a key that has it |
| 429 | Calling too fast | Back off and retry |