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 and edit 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
courses:read	View courses and their storyboards
courses:write	Create courses and run planning, storyboarding and generation
studio:read	View Studio projects and templates
studio:write	Create, edit and share Studio projects
modules:read	View training modules, results and qualifications
modules:write	Create, edit and translate training modules; record attempts and sign-offs
remixes:read	View remixes and their analysis
remixes:write	Create remixes and run analysis
recordings:read	View AI Recorder jobs and saved logins
recordings:write	Start recordings and manage saved logins
knowledge_base:read	View the knowledge base, its articles and analytics
knowledge_base:write	Create and edit knowledge base content
brand_kit:read	View Brand Kit settings, skills and glossary
brand_kit:write	Change Brand Kit settings, skills and glossary
usage:read	View usage statistics
voices:read	List available voices
voices:write	Delete cloned voices
avatars:read	List available AI avatars
avatars:write	Create custom AI avatars
webhooks:read	View webhook subscriptions
webhooks:write	Create, update, and delete webhooks
process:write	Use one-shot process endpoint
approvals:read	View approval rounds and requests
approvals:write	Request, decide and withdraw approvals
comments:read	View comments on videos
comments:write	Add and delete comments
locks:write	Lock and unlock videos and modules

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_*).