OmnAPI API Key Authentication

API Keys

Authenticate business API requests, including Generation queries, by sending your OmnAPI API key in the x-api-key HTTP header. Media URLs returned in playback.url are opened without that header; the public pricing catalog also does not require authentication.

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. Authenticated SDK and Postman requests use x-api-key only. Keep the key on your server; never append it to a media URL. Temporary playback URLs grant access to the audio and should not be logged or shared publicly. See Suno playback.

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.

Store the API key in a password manager or your platform’s secret store. Do not put it in source control or client-side application bundles.

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
storage:write	Enable or cancel paid Suno audio storage when available
*	All public API operations

See the operation permissions and billing matrix. A GET or task:read permission does not guarantee that an operation is free.

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 shares request allowances across all keys belonging to the same customer. Optional key sublimits and separate IP protection also apply. 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.