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
Read eventsList all events belonging to a user
Write eventsAbility to submit events (i.e. user activity)
Read countsCount users and companies with specified criteria
Write data attributesCreate and update custom data attributes
Export message dataExport engagement data for messages
Export content dataExport engagement data for content
Read content dataCreate and update custom data attributes
Read ticketsView tickets
Write ticketsCreate tickets

Workspace data

Extended scopesDescription
Read adminsList and view all admins
Read one adminView a single admin
Update adminsUpdate away mode for admins
Read admin activity logsList and view all admins and their activity
Read data when entered into the appGather data via Intercom Apps
Read and List news items and newsfeedsList and view all News items and Newsfeeds
Read and Write news items and newsfeedsRead, Update and Create news items and newsfeeds
Read and List articlesList and view all articles
Read and Write ArticlesRead, Update and Create articles
Create phone call redirectsCreate phone call redirects

🚧 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.