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 scopes
Description

Read and list users and companies

List and view all segments, users and companies

Read and write users

List all users and execute bulk actions

Write users and companies

Create and update users and companies

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

Write events

Ability to submit events (i.e. user activity)

Read events

List all events belonging to a user

Read counts

Count users and companies with specified criteria

Workspace data

Extended scopes
Description

Read admins

List and view all admins

Read one admin

View a single admin

Update admins

Update away mode for admins

Gather App data

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



OAuth Scopes


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.