Scopes

Permissions your app can request from Orshot users

Scopes define what your app can do on behalf of a user. Request only the scopes your app needs — users see these on the consent screen and are more likely to approve minimal permissions.

Available Scopes#

Scope	Description
`openid`	Access the user's unique ID (standard OpenID Connect)
`profile`	Read the user's profile info (name, avatar)
`email`	Read the user's email address
`workspace:read`	List and read workspace details
`workspace:templates:read`	List and read templates in granted workspaces
`workspace:templates:write`	Delete templates in granted workspaces
`render:generate`	Generate images, PDFs, and videos from templates
`mcp:access`	Access Orshot via the Model Context Protocol
`offline_access`	Receive a refresh token for long-lived access

Template creation and modification are Enterprise-only features and require an API key. Third-party OAuth apps can read and delete templates, but not create or update them.

Not all API endpoints are accessible via OAuth. See OAuth Endpoint Access for the full list.

Choosing Scopes#

Request the minimum your app needs. Here are common combinations:

Read-only dashboard / analytics#

workspace:read workspace:templates:read

Image generation tool#

workspace:read workspace:templates:read render:generate offline_access

Template management app#

workspace:read workspace:templates:read workspace:templates:write offline_access

This scope combination allows reading and deleting templates only. For full template management (create/update), use API keys with an Enterprise plan.

MCP / AI agent integration#

mcp:access workspace:read workspace:templates:read render:generate offline_access

How Scopes Work#

Scopes are requested in the scope parameter during authorization (space-separated)
Users see the requested scopes on the consent screen
The granted scopes are returned in the token response
Your client can only request scopes that were pre-approved during app registration

Include offline_access if your app needs to work in the background or maintain long-lived sessions. Without it, you'll only receive an access token (15-minute lifetime) and no refresh token — meaning the user would need to re-authorize after expiry.

If your app is a server-side integration that runs without user interaction (e.g., a cron job generating daily reports), you'll need offline_access to refresh tokens automatically.

Scope Validation#

If you request a scope your client isn't allowed, the authorization request will fail with invalid_scope
If a user re-authorizes your app with fewer workspaces, tokens for removed workspaces are automatically revoked
Scope changes require the user to re-authorize — you can't escalate permissions on an existing token

←

Device Flow

OAuth Endpoint Access

→