API Key Permission Scopes - HeyGen Documentation

Permission scopes let you restrict an API key to the HeyGen resources and actions it needs. Each scope uses the form resource:read or resource:write.

How permissions work

An endpoint can require one scope or several scopes. When several are listed, the key must satisfy all of them.
A resource:write grant also satisfies resource:read for the same resource. A read grant never satisfies a write requirement.
Full-access keys use *:*. Read-only keys use *:read, which satisfies every current and future read requirement.
A key without the required permissions receives a 403 insufficient_api_key_scope response.

Create and manage keys in the HeyGen API dashboard.

Scope-to-endpoint mapping

This reference is generated from the permission metadata in the published OpenAPI specification. Only public, documented endpoints are included. An endpoint with multiple requirements appears under every required scope.

`account:read`

Endpoint	Description	Required scopes
`GET /v3/users/me`	Get Current User	`account:read`

`ai_clipping:read`

Endpoint	Description	Required scopes
`GET /v3/ai-clipping`	List AI Clipping	`ai_clipping:read`
`GET /v3/ai-clipping/{job_id}`	Get AI Clipping	`ai_clipping:read`

`ai_clipping:write`

Endpoint	Description	Required scopes
`POST /v3/ai-clipping`	Create AI Clipping	`ai_clipping:write`
`DELETE /v3/ai-clipping/{job_id}`	Delete AI Clipping	`ai_clipping:write`

`assets:read`

Endpoint	Description	Required scopes
`GET /v3/assets/batches/{batch_id}`	Get Asset Batch	`assets:read`
`GET /v3/assets/statuses`	Bulk Asset Statuses	`assets:read`
`GET /v3/assets/{asset_id}`	Get Asset	`assets:read`
`GET /v3/audio/sounds`	Search audio (music or sound effects)	`assets:read`

`assets:write`

Endpoint	Description	Required scopes
`POST /v3/assets`	Upload Asset	`assets:write`
`POST /v3/assets/complete/batches`	Complete Asset Upload Batch	`assets:write`
`POST /v3/assets/direct-uploads`	Create Asset Upload	`assets:write`
`POST /v3/assets/direct-uploads/batches`	Create Asset Upload Batch	`assets:write`
`DELETE /v3/assets/{asset_id}`	Delete Asset	`assets:write`
`POST /v3/assets/{asset_id}/complete`	Complete Asset Upload	`assets:write`

`avatars:read`

Endpoint	Description	Required scopes
`GET /v3/avatars`	List Avatar Groups	`avatars:read`
`GET /v3/avatars/look-templates`	List Look Templates	`avatars:read`
`GET /v3/avatars/looks`	List Avatar Looks	`avatars:read`
`GET /v3/avatars/looks/{look_id}`	Get Avatar Look	`avatars:read`
`GET /v3/avatars/{group_id}`	Get Avatar Group	`avatars:read`

`avatars:write`

Endpoint	Description	Required scopes
`POST /v3/avatars`	Create Avatar	`avatars:write`
`POST /v3/avatars/looks`	Create Avatar Looks	`avatars:write`
`PATCH /v3/avatars/looks/{look_id}`	Update Avatar Look	`avatars:write`
`DELETE /v3/avatars/looks/{look_id}`	Delete Avatar Look	`avatars:write`
`PATCH /v3/avatars/{group_id}`	Update Avatar Group	`avatars:write`
`DELETE /v3/avatars/{group_id}`	Delete Avatar Group	`avatars:write`
`POST /v3/avatars/{group_id}/consent`	Create Avatar Consent	`avatars:write`

`brand:read`

Endpoint	Description	Required scopes
`GET /v3/brand-glossaries`	List Brand Glossaries	`brand:read`
`GET /v3/brand-glossaries/{brand_glossary_id}`	Get Brand Glossary	`brand:read`
`GET /v3/brand-kits`	List Brand Kits	`brand:read`
`GET /v3/brand-kits/{brand_kit_id}`	Get Brand Kit	`brand:read`

`brand:write`

Endpoint	Description	Required scopes
`POST /v3/brand-glossaries`	Create Brand Glossary	`brand:write`
`PATCH /v3/brand-glossaries/{brand_glossary_id}`	Update Brand Glossary	`brand:write`
`DELETE /v3/brand-glossaries/{brand_glossary_id}`	Delete Brand Glossary	`brand:write`
`POST /v3/brand-kits`	Create Brand Kit	`brand:write`
`PATCH /v3/brand-kits/{brand_kit_id}`	Update Brand Kit	`brand:write`
`DELETE /v3/brand-kits/{brand_kit_id}`	Delete Brand Kit	`brand:write`

`filler_removal:read`

Endpoint	Description	Required scopes
`GET /v3/filler-word-removals/{filler_word_removal_id}`	Get Filler Word Removal	`filler_removal:read`

`filler_removal:write`

Endpoint	Description	Required scopes
`POST /v3/filler-word-removals`	Create Filler Word Removal	`filler_removal:write`

`hyperframes:read`

Endpoint	Description	Required scopes
`GET /v3/hyperframes/renders`	List HyperFrames Renders	`hyperframes:read`
`GET /v3/hyperframes/renders/{render_id}`	Get HyperFrames Render	`hyperframes:read`

`hyperframes:write`

Endpoint	Description	Required scopes
`POST /v3/hyperframes/renders`	Create HyperFrames Render	`hyperframes:write`
`DELETE /v3/hyperframes/renders/{render_id}`	Delete HyperFrames Render	`hyperframes:write`

`images:read`

Endpoint	Description	Required scopes
`GET /v3/models/images/{generation_id}`	Get HeyGen Image	`images:read`

`images:write`

Endpoint	Description	Required scopes
`POST /v3/models/images`	Create HeyGen Image	`images:write`

`lipsync:read`

Endpoint	Description	Required scopes
`GET /v3/lipsyncs`	List Lipsyncs	`lipsync:read`
`GET /v3/lipsyncs/batches/{batch_id}`	Get Lipsync Batch	`lipsync:read`
`GET /v3/lipsyncs/statuses`	Bulk Lipsync Statuses	`lipsync:read`
`GET /v3/lipsyncs/{lipsync_id}`	Get Lipsync	`lipsync:read`

`lipsync:write`

Endpoint	Description	Required scopes
`POST /v3/lipsyncs`	Create Lipsync	`lipsync:write`
`POST /v3/lipsyncs/batches`	Create Lipsync Batch	`lipsync:write`
`PATCH /v3/lipsyncs/{lipsync_id}`	Update Lipsync	`lipsync:write`
`DELETE /v3/lipsyncs/{lipsync_id}`	Delete Lipsync	`lipsync:write`

`templates:read`

Endpoint	Description	Required scopes
`GET /v3/templates`	List Templates	`templates:read`
`GET /v3/templates/{template_id}`	Get Template	`templates:read`
`POST /v3/templates/{template_id}`	Generate Video from Template	`templates:read`, `videos:write`

`templates:write`

Endpoint	Description	Required scopes
`POST /v3/templates`	Create Template from Video	`templates:write`, `videos:read`
`PATCH /v3/templates/{template_id}`	Update Template	`templates:write`
`DELETE /v3/templates/{template_id}`	Delete Template	`templates:write`
`PUT /v3/templates/{template_id}/variables`	Set Template Variables	`templates:write`

`translations:read`

Endpoint	Description	Required scopes
`GET /v3/video-translations`	List Video Translations	`translations:read`
`GET /v3/video-translations/batches/{batch_id}`	Get Video Translation Batch	`translations:read`
`GET /v3/video-translations/languages`	List Supported Translation Languages	`translations:read`
`GET /v3/video-translations/proofreads`	List Proofread Sessions	`translations:read`
`GET /v3/video-translations/proofreads/{proofread_id}`	Get Proofread Session	`translations:read`
`GET /v3/video-translations/proofreads/{proofread_id}/srt`	Download Proofread SRT	`translations:read`
`GET /v3/video-translations/statuses`	Bulk Video Translation Statuses	`translations:read`
`GET /v3/video-translations/{video_translation_id}`	Get Video Translation	`translations:read`

`translations:write`

Endpoint	Description	Required scopes
`POST /v3/video-translations`	Create Video Translation	`translations:write`
`POST /v3/video-translations/batches`	Create Video Translation Batch	`translations:write`
`POST /v3/video-translations/proofreads`	Create Proofread Session	`translations:write`
`DELETE /v3/video-translations/proofreads/{proofread_id}`	Delete Proofread Session	`translations:write`
`POST /v3/video-translations/proofreads/{proofread_id}/generate`	Generate Video from Proofread	`translations:write`
`PUT /v3/video-translations/proofreads/{proofread_id}/srt`	Upload Proofread SRT	`translations:write`
`PATCH /v3/video-translations/{video_translation_id}`	Update Video Translation	`translations:write`
`DELETE /v3/video-translations/{video_translation_id}`	Delete Video Translation	`translations:write`

`video_agent:read`

Endpoint	Description	Required scopes
`GET /v3/video-agents`	List Video Agent Sessions	`video_agent:read`
`GET /v3/video-agents/styles`	List Video Agent Styles	`video_agent:read`
`GET /v3/video-agents/{session_id}`	Get Video Agent Session	`video_agent:read`
`GET /v3/video-agents/{session_id}/resources/{resource_id}`	Get Session Resource	`video_agent:read`
`GET /v3/video-agents/{session_id}/videos`	List Session Videos	`video_agent:read`

`video_agent:write`

Endpoint	Description	Required scopes
`POST /v3/video-agents`	Create Video Agent Session	`video_agent:write`
`POST /v3/video-agents/{session_id}`	Send Video Agent Message	`video_agent:write`
`POST /v3/video-agents/{session_id}/stop`	Stop Video Agent Session	`video_agent:write`

`videos:read`

Endpoint	Description	Required scopes
`GET /v3/folders/{folder_id}`	Get Folder	`videos:read`
`GET /v3/models/videos/{video_id}`	Get HeyGen Video	`videos:read`
`POST /v3/templates`	Create Template from Video	`templates:write`, `videos:read`
`GET /v3/videos`	List Videos	`videos:read`
`GET /v3/videos/batches/{batch_id}`	Get Video Batch	`videos:read`
`GET /v3/videos/statuses`	Bulk Video Statuses	`videos:read`
`GET /v3/videos/{video_id}`	Get Video	`videos:read`
`GET /v3/videos/{video_id}/scenes`	Get Video Scenes	`videos:read`

`videos:write`

Endpoint	Description	Required scopes
`POST /v3/folders`	Create Folder	`videos:write`
`POST /v3/models/videos`	Create HeyGen Video	`videos:write`
`POST /v3/templates/{template_id}`	Generate Video from Template	`templates:read`, `videos:write`
`POST /v3/videos`	Create Video	`videos:write`
`POST /v3/videos/batches`	Create Video Batch	`videos:write`
`DELETE /v3/videos/{video_id}`	Delete Video	`videos:write`

`voices:read`

Endpoint	Description	Required scopes
`GET /v3/models/audio/voices`	List Audio Voices	`voices:read`
`GET /v3/models/audio/voices/{voice_id}`	Get an Audio Voice	`voices:read`
`GET /v3/voices`	List Voices	`voices:read`
`GET /v3/voices/{voice_id}`	Get Voice	`voices:read`

`voices:write`

Endpoint	Description	Required scopes
`POST /v3/models/audio/tts`	Generate Speech	`voices:write`
`POST /v3/models/audio/tts/stream`	Stream Speech	`voices:write`
`POST /v3/models/audio/voices`	Create or Retrain an Audio Voice	`voices:write`
`DELETE /v3/models/audio/voices/{voice_id}`	Delete an Audio Voice	`voices:write`
`POST /v3/voices`	Design a Voice	`voices:write`
`POST /v3/voices/clone`	Clone a Voice	`voices:write`
`POST /v3/voices/speech`	Generate Speech	`voices:write`
`DELETE /v3/voices/{voice_id}`	Delete a Voice	`voices:write`

`webhooks:read`

Endpoint	Description	Required scopes
`GET /v3/webhooks/endpoints`	List Webhook Endpoints	`webhooks:read`
`GET /v3/webhooks/event-types`	List Webhook Event Types	`webhooks:read`
`GET /v3/webhooks/events`	List Webhook Events	`webhooks:read`

`webhooks:write`

Endpoint	Description	Required scopes
`POST /v3/webhooks/endpoints`	Create Webhook Endpoint	`webhooks:write`
`PATCH /v3/webhooks/endpoints/{endpoint_id}`	Update Webhook Endpoint	`webhooks:write`
`DELETE /v3/webhooks/endpoints/{endpoint_id}`	Delete Webhook Endpoint	`webhooks:write`
`POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret`	Rotate Webhook Signing Secret	`webhooks:write`

​How permissions work

​Scope-to-endpoint mapping

​account:read

​ai_clipping:read

​ai_clipping:write

​assets:read

​assets:write

​avatars:read

​avatars:write

​brand:read

​brand:write

​filler_removal:read

​filler_removal:write

​hyperframes:read

​hyperframes:write

​images:read

​images:write

​lipsync:read

​lipsync:write

​templates:read

​templates:write

​translations:read

​translations:write

​video_agent:read

​video_agent:write

​videos:read

​videos:write

​voices:read

​voices:write

​webhooks:read

​webhooks:write