Developer Guide
Scopes Reference
Fine-grained permission scopes let you limit what an API key or OAuth client can access within a workspace.
Overview
Scopes are space-separated strings attached to an API key or OAuth client. When a request arrives, the API validates the token's scopes against the operation being performed. This follows the same model as GitHub and Stripe - familiar, auditable, and easy to reason about.
Scopes are optional. If no scopes are specified, the credential has full access to the workspace (equivalent to a workspace admin). We recommend assigning the minimum scopes needed for each integration.
Scopes
| Scope | What it grants | Methods | Endpoints |
|---|---|---|---|
polls:read | Read polls, their content, and metadata. | GET | /polls, /polls/{id} |
polls:write | Create, update, and delete polls. | POST, PATCH, DELETE | /polls, /polls/{id} |
results:read | Read aggregated results, individual responses, and votes. | GET | /polls/{id}/results, /polls/{id}/responses, /polls/{id}/votes |
responses:write | Submit responses and votes to polls. | POST | /polls/{id}/responses, /polls/{id}/votes |
sessions:write | Create and control live presenter sessions. | POST | /sessions, /sessions/{id}/control |
sessions:read | Read live session state, participants, and leaderboard. | GET | /sessions/{id} |
media:write | Upload and proxy media (images, YouTube) for use in questions. | POST | /media |
export:read | Download poll results as CSV. | GET | /polls/{id}/export |
ai:write | Use AI branching to add conditional logic to polls. | POST | /polls/{id}/branch |
Scopes on API keys
API key scopes are enforced on every request. A key created with a non-empty scope set may only call endpoints covered by those scopes - a request that needs a scope the key lacks returns 403 insufficient_scope. A key created with no scopes has full workspace access (see Default below). Assign a key's scopes when you create it in the Developer portal.
Scopes on OAuth clients
OAuth clients enforce scopes at token issuance time. When you call POST /api/oauth/token with a scope parameter, only scopes that were assigned to the client at creation time are granted. Requesting an unassigned scope is silently dropped from the token.
If no scope is sent in the token request, the token inherits all scopes assigned to the client (or full access if the client has no scopes).
See the OAuth 2.0 guide for a full setup walkthrough.
Default (no scopes specified)
Credentials with no scopes attached have full workspace access - equivalent to a workspace admin. Use this for:
- Personal automation where you own the workspace
- Prototyping and development
For production integrations shared across teams or third parties, always specify the minimum required scopes.
Still have questions?
Our team is happy to help.