OAuth Scopes

OAuth scopes, or permissions, let you specify exactly how your application needs to access an Intercom user's account.

You should only specify the scopes you need to satisfy your use case and no more. Scopes are the most common reason that apps aren't approved when it comes to reviews.

Summary of all Oauth Scopes

The following scopes can be selected via checkboxes on your Authorization settings page in the developer hub:

People & conversation data

Standard scopesDescription
Read and list users and companiesList and view all segments, users and companies
Read and write usersList all users and execute bulk actions
Write users and companiesCreate and update users and companies
Read one user and one companyList and view a single user and company
Read tagsList all tags
Write tagsCreate, update, use and delete tags
Read conversationsView conversations
Write conversationsReply to, mark as read and close conversations
Write eventsAbility to submit events (i.e. user activity)
Read eventsList all events belonging to a user
Read countsCount users and companies with specified criteria

Workspace data

Extended scopesDescription
Read adminsList and view all admins
Read one adminView a single admin
Update adminsUpdate away mode for admins
Gather App dataGather data for apps utilizing Canvas Kit

🚧

Canvas Kit required scopes

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

📘

Selecting webhook topics

Webhook topics are related to corresponding 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. Checkout our docs on setting up webhooks for more detailed information on how to enable webhooks for your app.