OmnAPI API Key Authentication

API Keys

Authenticate every public API request by sending your OmnAPI API key in the x-api-key HTTP header.

GET /api/v1/tasks/task_01H... HTTP/1.1
Host: api.omnapi.com
x-api-key: sk_live_...

The public API does not accept API keys in the Authorization: Bearer header. Public docs, SDKs, and Postman samples use x-api-key only; internal service keys and operator-issued machine automation credentials are private runbook material, not customer API credentials.

Auth error responses

Status	code	Cause
401	INVALID_API_KEY	Header missing or malformed, or the key/account is inactive or expired.
403	FORBIDDEN	Key lacks the required scope or the caller IP is outside its allowlist.
429	RATE_LIMITED	Active request limit exceeded — see Rate Limits.

All auth failures return the shared error envelope:

{
  "success": false,
  "error": { "code": "INVALID_API_KEY", "message": "Missing API key" }
}

Getting a key

1. Sign in to API Keys in the OmnAPI dashboard.
2. Click Create key, label it, then copy the displayed API key.

You will only see the API key once. Store it in a password manager or your platform’s secret store.

Rotating a key

1. Create a new key first (so you have overlap).
2. Update your application to the new key.
3. Disable the previous key from the dashboard.
4. After ≥ 24h of zero traffic on the previous key, delete it.

Scoping & limits

An unrestricted key has an empty scope list or the * scope. When a key has a non-empty scope list, every operation requires the matching value:

Scope	Allows
task:create	Create generic tasks and use task-producing Producer, Lyrics, Subtitles, Vidu, Suno, and MV write endpoints
task:read	List/read/stream tasks and read product resources
task:cancel	Cancel generic, Vidu, or MV task operations
usage:read	Read account credits and export usage
*	All public API operations

Keys can also carry an IP allowlist. An empty list permits any source IP; a non-empty list requires the resolved client IP to match one listed address exactly. Scope or IP rejection returns 403 FORBIDDEN. Its details may include requiredScope or the resolved clientIp for diagnosis.

OmnAPI also applies per-key and per-IP request limits. Higher production allowances can be reviewed with support; see Rate Limits.

Safe handling

Practice	Guidance
Server-side use	Recommended for production. Keep keys in a secret manager or environment variable.
Browser use	Avoid exposing production keys in public client code. The docs playground stores a key locally only for your own session.
Logging	Never log raw keys, request headers, or full webhook URLs containing secrets.
Rotation	Rotate keys periodically and immediately after any suspected exposure.

The interactive playground keeps keys in the current browser session and sends requests directly to api.omnapi.com.

Compromised key checklist

1. Disable the key from the dashboard immediately.
2. Review recent usage in Apps Usage for unexpected calls.
3. Rotate any keys derived from the same source (e.g., copy-pasted into shared workspaces).
4. File a support ticket if you need help investigating unexpected usage.