What OAuth scopes can I request?
The full list of Orshot OAuth scopes and what each grants read or write access to.
Published ·Updated
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 |
|---|---|
workspace:read | List and read workspace details |
workspace:templates:read | List and read templates in granted workspaces |
workspace:templates:write | Delete, share and move templates, manage folders and versions |
render:generate | Generate images, PDFs, and videos from templates |
mcp:access | Marks the connection as an MCP client. It adds no API access by itself |
offline_access | Long-lived access (a refresh token is always returned) |
Template creation and modification are Enterprise-only features and require an API key. Third-party OAuth apps can read, delete, share and organize templates and manage their versions, but not create templates or edit their layers.
To read the connected account and its workspaces, call GET /v1/me with workspace:read. See Examples.
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:readImage generation tool#
workspace:read workspace:templates:read render:generate offline_accessTemplate management app#
workspace:read workspace:templates:read workspace:templates:write offline_accessThis combination can read, delete, share and organize templates and manage versions. To create templates or edit their layers, use an API key on an Enterprise plan.
MCP / AI agent integration#
mcp:access workspace:read workspace:templates:read render:generate offline_accessHow Scopes Work#
- Scopes are requested in the
scopeparameter 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 it has registered. You set them during app registration and can change them in the dashboard at any time
The offline_access Scope#
Every token response includes a refresh token, with or without offline_access. Request offline_access anyway when your app works in the background (for example, a cron job that renders daily reports), so the consent screen lists Offline access among the permissions.
Approvals Scopes#
The Approvals API has four scopes of its own. They are not listed in the discovery document, so request them by name.
| Scope | Grants |
|---|---|
workspace:approvals:read | See approval flows, stages, where templates sit, comments and activity |
workspace:approvals:write | Add and move templates, comment, manage your notifications (includes read) |
workspace:approvals:decide | Approve or request changes where you are an approver (includes read) |
workspace:approvals:admin | Create and change flows, stages, groups and approvers (includes write and read, not decide) |
Your own OAuth app also needs the Approvals API turned on for the workspace. See Approvals overview.
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
- Existing tokens keep the scopes they were issued with. Users get new scopes only when they authorize again
Ready to automate?
Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.
Get your API key- Image, PDF and video generation via API
- Visual editor with AI and smart layouts
- Zapier, Make, MCP and 40+ integrations
- White-label embed for your own app
- 100 free credits a month, no credit card required