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
`projects:read`	View project folders
`projects:write`	Create, update, and delete project folders
`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"
  }
}

Scopes are not the only gate

A scope says what your integration asked for. The workspace role of the user who authorized it says what that person may do, and both must allow the action. A token granted videos:write by someone whose role is viewer is still refused, with insufficient_role.

Role	Can create	Can edit	Can delete	Can export
`owner`, `admin`, `creator`	yes	yes	yes	yes
`developer`, `editor`	no	yes	no	yes
`viewer`	no	no	no	yes

Request the narrowest scopes you need, and expect that some users will authorize your app with less power than the scopes imply.

Scope-to-endpoint mapping

Endpoint	Required scope
`GET /v1/videos`	`videos:read`
`POST /v1/videos/upload`	`videos:write`
`GET /v1/projects`	`projects:read`
`GET /v1/projects/:id`	`projects:read`
`POST /v1/projects`	`projects:write`
`PATCH /v1/projects/:id`	`projects:write`
`DELETE /v1/projects/:id`	`projects: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_*).

Available scopes​

Requesting scopes​

Scope enforcement​

Scopes are not the only gate​

Scope-to-endpoint mapping​

API keys and scopes​