Scopes describe the access your integration is requesting. You send them as a space-delimited list in the scope parameter of your authorisation or token request.
Your client is configured with a set of allowed scopes when your credentials are issued. Requesting a scope outside that set returns an invalid_scope error.
| Scope | Description |
|---|---|
api1 | Access to the Partner API. Every Partner API endpoint requires this scope — without it, your token will be rejected. |
read | Read access to data. |
write | Write access to data, including creating and updating records. |
offline_access | Issues a refresh token, allowing your integration to obtain new access tokens without the user re-authorising. |
Request the minimum set of scopes your integration needs. Users see every scope you request on the consent screen, so unnecessary requests both reduce the chance of approval and increase your exposure if credentials are compromised.
Send scopes as a space-delimited list:
scope=api1 offline_access readIn a URL, the spaces are encoded:
scope=api1%20offline_access%20readRead-only integrations — api1 read, plus offline_access if your integration runs unattended.
Read and write integrations — api1 read write, plus offline_access if needed.
Consider whether you need write at all. An integration that only retrieves documents and company data does not, and requesting it anyway asks customers to grant more than you use.
offline_access is what gets you a refresh token. Without it, your integration must send the user through authorisation again every time the access token expires — which makes any scheduled or background processing impossible.
Include it if your integration:
- Runs on a schedule, or in the background.
- Needs to act when the user is not present.
- Should not prompt the user repeatedly during normal operation.
See Managing Access and Refresh Tokens for how refresh tokens behave once issued.
The token response includes the scope actually granted, which may be narrower than what you asked for — for example, if your client is not configured for a scope you requested.
Check the granted scope rather than assuming your request was fulfilled in full.
- Authorisation Code Flow — where scopes are requested.
- Managing Access and Refresh Tokens — what
offline_accessgets you. - Error codes — troubleshooting
invalid_scope.