Authentication

The Clipwave API uses Bearer token authentication with API keys you generate from your dashboard.

Key format

API keys look like:

cw_live_<32 base64url chars>

The plaintext is shown exactly once at creation time. Clipwave stores only a SHA-256 hash; we cannot recover lost keys. If you lose a key, revoke it and create a new one.

Sending the key

Include the API key in the Authorization header on every request:

Authorization: Bearer cw_live_AbCd1234...

Example:

curl https://clipwave.ai/api/v1/models \
  -H "Authorization: Bearer cw_live_AbCd1234..."

Missing or invalid header → 401 Unauthorized. Revoked key → 401 Unauthorized.

Creating keys

1. Sign in at clipwave.ai.
2. Dashboard → API Keys.
3. Click Create key, give it a label ("MCP server", "Production", "Local dev").
4. Copy the cw_live_... plaintext immediately. You will not see it again.

You can create multiple keys (one per environment, one per integration). Revoke individually.

Scopes

Each key carries scopes that limit what it can do. Default scopes assigned at creation:

Scope	Permits
video:write	POST /api/v1/video/*/generate
image:write	POST /api/v1/image/*/generate
jobs:read	GET /api/v1/jobs/:id
models:read	GET /api/v1/models
video-editor:read	GET /api/v1/media-studio/projects[/:id]
video-editor:write	POST /api/v1/media-studio/projects[/:id/{instruct,export}]

Scopes that DO NOT exist yet but reserved for future use:

• jobs:cancel (currently grouped under video:write/image:write)
• keys:manage

A request to an endpoint outside your key's scopes returns 403 Forbidden with the message Missing required scope: <scope>.

Scope enforcement design

By design, read-only endpoints (GET /api/v1/models, GET /api/v1/jobs/:id) do NOT enforce scopes beyond requiring a valid key. Any active key whose owner created the job can read its status; any active key can list models. The models:read and jobs:read scopes are present in the default scope set for forward compatibility, but no current endpoint rejects a request for missing them. Mutating endpoints (POST /generate, DELETE /jobs/:id) DO enforce video:write / image:write strictly.

Rate limits

• 60 requests per minute per API key (in-memory sliding window).
• Exceed → 429 Too Many Requests with Retry-After: <seconds> header.
• Successful responses include X-RateLimit-Remaining and X-RateLimit-Reset (seconds until window resets).

This in-memory limiter is per-process. Multi-instance Redis-backed limiting is on the roadmap.

Revoking keys

Dashboard → API Keys → Revoke next to the key.

Revocation is immediate. Subsequent requests with that key return 401 Unauthorized.

The api_keys table marks the row with revoked_at = NOW() rather than deleting it, so audit logs (api_requests) remain attributable.

Security best practices

• Never commit keys to git. Use environment variables.
• Use distinct keys per environment (production vs staging vs local dev).
• Rotate periodically (every 90 days is a reasonable default for sensitive integrations).
• Revoke immediately if a key may have been exposed (committed, logged, screenshot, etc.).
• Treat any 4xx response with error: "Invalid or revoked API key" after a code deploy as a sign that you accidentally rotated the wrong env file.

Audit log

Every request (success or failure) is logged to the api_requests table:

CREATE TABLE api_requests (
  id BIGSERIAL PRIMARY KEY,
  api_key_id INTEGER REFERENCES api_keys(id) ON DELETE SET NULL,
  user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
  endpoint TEXT NOT NULL,
  method TEXT NOT NULL,
  status_code INTEGER,
  credits_consumed INTEGER NOT NULL DEFAULT 0,
  job_id TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Future: a UI to inspect your own audit log will live at Dashboard → API Keys → Activity.