API Key Scopes

Scopes are how you give an integration the least it needs. A scope is one of the project permissions you already know from the members page, using the same name. There is no second vocabulary to learn.

The One Rule

A key's effective permissions in a project are the creator's permissions AND the key's scopes. Scopes subtract. A key with the deleteAssets scope created by someone who cannot delete assets still cannot delete assets. A key with only viewAssets created by an owner with every permission can only view.

Restrictions on the creator carry through untouched: if the creator may only see published assets, or must receive watermarked downloads, so must the key.

Presets

The create-key dialog offers three presets. They are shorthand for the scope sets below; the key stores plain scopes, so you can start from a preset and adjust.

Preset	Scopes	Use it for
Read	`viewAssets`, `viewTags`, `viewApprovals`	Dashboards, sync checks, anything that never writes
Ingest	`viewAssets`, `uploadAssets`, `createFolders`, `viewTags`	Camera carts, watch folders, migration tools
Metadata	`viewAssets`, `editMetadata`, `viewTags`, `createTags`	Captioning and credit tools, DAM sync

All Scopes

Grouped as they appear in the app. "Used by" names the parts of the API reference that require the scope.

Assets

Scope	Allows	Used by
`viewAssets`	Browse and read assets, folders, and collections	Every list and get route
`uploadAssets`	Create assets through the upload protocol	Uploads
`editMetadata`	Change title, description, keywords, creator, and copyright	Update asset metadata
`deleteAssets`	Delete assets, singly or in bulk	Delete asset, bulk delete
`downloadAssets`	Receive signed download URLs for originals	Get download URL
`managePublishing`	Publish and unpublish assets	Publish, unpublish
`hideAssets`	Hide and unhide assets	Hide, unhide
`viewHiddenAssets`	See hidden assets at all; without it they are not found	Any route addressing a hidden asset
`moveAssets`	Move assets between folders	Move asset

Folders

Scope	Allows	Used by
`createFolders`	Create folders	Create folder
`renameFolders`	Rename folders	Rename folder
`deleteFolders`	Delete folders	Delete folder

Scope	Allows	Used by
`viewTags`	List the project's tags and see tags on assets; without it an asset's `tags` is empty	List tags, asset reads
`createTags`	Apply existing project tags to assets	Tag asset
`deleteTags`	Remove tags from assets	Remove tag from asset

Collections

Scope	Allows	Used by
`createCollections`	Create collections	Create collection
`editCollections`	Rename, describe, and change the contents of collections	Update collection, add and remove assets
`deleteCollections`	Delete collections	Delete collection
`manageCollectionMembers`	Share a collection with project members	List, add, and remove collection members
`shareCollectionsInternal`, `shareCollectionsExternal`	Collection share links	No v1 route yet; share links stay in the app

Every collection route also needs viewAssets.

Approvals and talent access

Scope	Allows	Used by
`viewApprovals`	List approvals and read their status	List and get approvals
`createTalentAccess`	Create approvals	Create approval
`manageTalentAccess`	Update, deactivate, and regenerate approvals	Update, delete, regenerate passcode
`manageApprovals`	Approve or reject on talent's behalf	No v1 route yet

Upload links

Scope	Allows	Used by
`createDistributionLinks`	Create upload links for outside contributors; also needs `uploadAssets`	Create upload link
`manageDistributionLinks`	List, revoke, and resend upload links	List, revoke, resend

Reporting

Scope	Allows	Used by
`viewAnalytics`, `viewAuditLogs`	Project analytics and activity	No v1 route yet

Never Scopeable

Running the project itself (its settings, its members and their permissions, and deleting it) is never available to a key, even one created by an owner. A key works in a project; a person runs it.

Choosing Scopes

Start from a preset and add one scope at a time as the integration grows.
One key per system. A shared key is impossible to revoke without breaking everything that uses it.
A key that needs deleteAssets or deleteCollections deserves a short expiry and a named owner.

What's Next

Uploading Files: what the Ingest preset is for
Errors: how a missing scope shows up in responses