OAuth Scopes

Scopes control what an OAuth token can access. Users see scope descriptions on the consent screen before approving.

Available scopes

Scope	Description
videos:read	View videos in the workspace
videos:write	Upload and modify videos
subtitles:read	View subtitles
subtitles:write	Generate subtitles
export:write	Export videos
translate:write	Translate videos
voiceover:write	Generate voiceovers
article:read	View help articles
article:write	Generate help articles
analyze:write	Analyze videos
tools:read	List and view tools
tools:write	Execute tools
jobs:read	View job status
usage:read	View usage statistics
process:write	Use one-shot process endpoint

Requesting scopes

Pass scopes as a space-separated string in the authorization URL:

scope=videos:read+analyze:write+jobs:read

Or URL-encoded:

scope=videos%3Aread%20analyze%3Awrite%20jobs%3Aread

Scope enforcement

• Tokens can only use the scopes that were approved by the user
• Requesting an endpoint without the required scope returns 403:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the \"export:write\" scope. Your token has: videos:read, analyze:write"
  }
}

Scope-to-endpoint mapping

Endpoint	Required scope
GET /v1/videos	videos:read
POST /v1/videos/upload	videos:write
POST /v1/videos/:id/analyze	analyze:write
POST /v1/videos/:id/export	export:write
POST /v1/videos/:id/translate	translate:write
GET /v1/videos/:id/subtitles	subtitles:read
POST /v1/videos/:id/voiceover	voiceover:write
POST /v1/videos/:id/article	article:write
POST /v1/videos/process	process:write
GET /v1/tools	tools:read
POST /v1/tools/:type/execute	tools:write
GET /v1/jobs/:id	jobs:read
GET /v1/usage	usage:read

API keys and scopes

API keys (vdo_live_*) bypass scope checks entirely — they have full access to all endpoints allowed by the workspace plan. Scopes only apply to OAuth access tokens (vdo_oat_*).