When you configure OAuth you will need to define the OAuth scopes, and these will be reviewed when you submit your app for approval. This guide will help you understand what OAuth scopes are, which ones are available, and how to choose them.
OAuth scopes, or permissions, let you specify exactly what types of data your app can access within an Intercom workspace and actions that it can take with the workspace's data.
You select OAuth scopes when you are configuring OAuth in your Developer Hub.
OAuth scopes are important because they define the level of access your app has to specific pieces of customer data. For the security of our customers, Intercom ensures that public apps only access resources necessary to the functionality of the app.
It's important that you only specify the scopes you need to satisfy your use case and no more.
Over-privileged scopes are the most common reason that apps are initially rejected in the approval process.
It's also important to note that if you are using Canvas Kit for Messenger or Inbox apps, certain OAuth scopes are required by default.
If your app utilizes Canvas Kit, certain permissions are required by default due to the data your app will have access to. The following scopes will be automatically selected and cannot be deselected:
- Read and list users and companies
- Read conversations
- Read admins
- Gather App data
The following scopes can be selected via checkboxes on your Authorization settings page in the Developer Hub:
| Standard scopes | Description |
|---|---|
| Read and list users and companies | List and view all segments, users, companies, and tags |
| Read and write users | List all users, execute bulk actions, and add or remove users from companies |
| Write users and companies | Create and update users, companies, and tags |
| Read one user and one company | List and view a single user and company |
| Read tags | List all tags |
| Write tags | Create, update, use and delete tags |
| Read conversations | View conversations |
| Write conversations | Reply to, mark as read and close conversations |
| Delete conversations and metrics | Delete conversations and their metrics, cannot be recovered |
| Read events | List all events belonging to a user |
| Write events | Ability to submit events (i.e. user activity) |
| Read counts | Count users and companies with specified criteria |
| Write data attributes | Create and update custom data attributes |
| Export message data | Export engagement data for messages |
| Export content data | Export engagement data for content |
| Read content data | Create and update custom data attributes |
| Read tickets | View tickets |
| Write tickets | Create tickets |
| Read and write custom object instances | Create, read, update and delete custom object instances |
| Read status of jobs | Read status of jobs enqueued via the API |
| Extended scopes | Description |
|---|---|
| Read admins | List and view all admins |
| Read one admin | View a single admin |
| Update admins | Update away mode for admins |
| Read admin activity logs | List and view all admins and their activity |
| Read data when entered into the app | Gather data via Intercom Apps |
| Read and List news items and newsfeeds | List and view all News items and Newsfeeds |
| Read and Write news items and newsfeeds | Read, Update and Create news items and newsfeeds |
| Read and List articles | List and view all articles |
| Read and Write Articles | Read, Update and Create articles |
| Create phone call redirects | Create phone call redirects |
| Read and list news items and newsfeeds | List and view all News items and Newsfeeds |
| Read and write news items and newsfeeds | Read, update and create news items and newsfeeds |
| Read and write AI content | Create and update AI content |
| Read data connectors | Access data connectors, execution results and execution webhooks |
| Read and write data connectors | Configure data connectors and read execution results and execution webhooks |
The Read conversations and Write conversations scopes do not on their own give your app access to every conversation in a workspace. Your app's token is also limited by the conversation access of the teammate who installed it:
- For a public app, that is the teammate who authorized your app through OAuth.
- For a private app, that is the teammate who installed the app on the workspace, or who last regenerated its Access Token.
Workspace admins set a teammate's conversation access under Settings > Workspace > Teammates. If the installing teammate can access All conversations, which is the default, your app can reach every conversation its scopes allow. If their access is limited, for example to conversations assigned to them or to their teams, your app's token is limited in the same way:
- Requests that act on a single conversation outside the teammate's access return a
403error with the codetoken_unauthorized. This applies to retrieving, updating, deleting, replying to, managing, merging, converting and redacting a conversation, to attaching or detaching its contacts and tags, and to the other endpoints that act on a single conversation. - List and search return only the conversations the teammate can access.
conversation.*webhook topics are delivered only for conversations the teammate can access.
{
"type": "error.list",
"request_id": "...",
"errors": [
{
"code": "token_unauthorized",
"message": "Not authorized to access this conversation"
}
]
}Requests from a Canvas Kit app are checked against the installing teammate's access, not against the access of the teammate who is viewing the Inbox.
Changes to the teammate's conversation access apply to your app's requests straight away. You do not need to reinstall the app or regenerate its token. To let your app work across all conversations, have it installed by a teammate whose conversation access is All conversations.
This applies to all API versions.
Webhook topics are related to corresponding OAuth permission scopes.
For example, if you need to setup a webook to trigger when a user/lead is created then you will need to select the "Read and write users" permission scopes.
You will then be able to setup the webhook topics for your app which will fire for each workspace it is installed on.
See the guide on setting up webhooks for more information on how to enable webhooks for your app.