Scopes

A key carries a set of scopes, chosen when you create it and fixed for its life. To change them, mint a new key and revoke the old one.

A new key defaults to read and generate — enough to create content and render video, nothing destructive.

What each scope grants

read

List and view. Never changes anything.

Method	Endpoint
GET	/contents
GET	/contents/{content_id}
GET	/contents/{content_id}/versions
GET	/personas
GET	/personas/{persona_id}
GET	/accounts
GET	/accounts/{account_id}
GET	/gen/static-videos
GET	/gen/task-status/{content_id}
GET	/users/credits
GET	/subscription/current

generate

Produce output. Spends credits.

Method	Endpoint
POST	/contents
POST	/gen/tts
POST	/gen/video
POST	/gen/process-content-async

POST /contents needs generate rather than write because creating content generates its script, which costs credits.

write

Create and edit. Non-destructive.

Method	Endpoint
PUT	/contents/{content_id}
POST	/personas
PUT	/personas/{persona_id}
PUT	/accounts/{account_id}

upload

Publish to connected social accounts.

Method	Endpoint
POST	/contents/upload/{content_id}

delete

Permanently removes things. Opt-in, and absent from the default set.

Method	Endpoint
DELETE	/contents/{content_id}
DELETE	/personas/{persona_id}

Content deletion is a soft delete — the item disappears from every read path, but a video already published to a platform keeps working. Persona deletion is permanent.

No scope required

GET /api-keys/introspect works with any valid key regardless of scopes.

When a scope is missing

403, naming what it wanted:

{
  "error": "insufficient_scope",
  "required": ["write"]
}

This is distinct from 401, which means the key itself is missing, malformed, invalid or revoked.

Choosing scopes

Grant the narrowest set that does the job. Concretely:

• A dashboard that only displays things needs read alone.
• A pipeline that creates and renders videos needs read + generate.
• Add upload only if that same key actually publishes.
• Add delete only if something genuinely needs to remove data. Most integrations never do, and an unattended script with delete is the one combination worth thinking twice about.

Separate keys per integration cost nothing and let you revoke one without disturbing the others.

A note on MCP

Keys minted through the MCP consent flow are drawn from a deliberately narrower set: delete is not offered there. Destructive access is limited to keys you create by hand in Settings, where the grant is explicit and attributable to you.