Getting started
Scopes
Every token carries scopes, chosen when an API key is created or approved on the OAuth consent screen. Each endpoint needs one of them.
Available scopes
Pick scopes when you create an API key, or request them in an OAuth authorization (scope, space-separated). The lookups (tags, departments, products) accept any read scope, and team members (users) need tickets:read.
| Scope | Access | Allows |
|---|---|---|
tickets:read | Read | List, search and read tickets, their replies, notes and custom fields. |
tickets:write | Write | Create tickets, reply, add notes, assign, change status or fields, and merge tickets. |
customers:read | Read | List and read customers (team owners and admins only). |
customers:write | Write | Create and update customers (team owners and admins only). |
conversations:read | Read | Read channel conversations and their messages. |
conversations:write | Write | Reply to conversations, add internal notes, assign, resolve and reopen them, and show live chat visitors you are typing. |
knowledge:read | Read | Search the help center and knowledge sources, and ask for cited answers. |
licenses:read | Read | Look up and verify license keys and purchases. |
webhooks:manage | Write | Subscribe and unsubscribe webhooks for Zapier, n8n or Make (owners and admins only), for the events the app may read. |
Scopes per endpoint
A call without the scope it needs answers 403, and the message names the missing scope.
Keys made before scopes
API keys made before scopes existed keep working as before: read-only keys can call every GET endpoint, read-write keys every endpoint.