# Scopes

> Permissions your app can request from Orshot users

- **URL**: https://orshot.com/docs/developers/scopes

---

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         |

## 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
```### 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](https://orshot.com/docs/developers/register-app)

## The `offline_access` Scope

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.

## 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