Create an Access Token

Note: Access Tokens have replaced API Keys

If you're currently using API Keys to access the Intercom API, you should switch to using Access Tokens before API Keys are deprecated in early-2018.

You'll need an Access Token if you want to use the API to access data in your own Intercom app.

If you intend to make an integration available publicly, and therefore need to access other people's Intercom data, you will need to set up OAuth instead.

If you're unsure, use this guide to work out whether you need an Access Token or OAuth.

Access Tokens should never be shared outside of your company

Your Access Token can give access to your private Intercom data and should be treated like a password. If an integration provider asks you for your Access Token, please do not do so and let us know - integrations are required to use OAuth rather than asking users for Access Tokens.

Creating your Access Token

Creating your Access Token is simple and you can get a Token with Standard scopes instantly (see below for more on scopes).

To create your Access Token, go to the dashboard in the Intercom Developer Hub by clicking here or by clicking on Dashboard at the top of the page and click 'Get an Access Token'.

Choosing your Token scopes

When you setup your Token, you will be asked to choose between two levels of scopes (i.e. permissions):

  • Standard Scopes: these scopes will be approved and useable straight away
  • Extended Scopes: these scopes require approval as they access more sensitive data – we usually approve requests within 24 hours. You'll be able to use standard scopes in the meantime.

You can update your scopes at any time.

Remember: Access Tokens only access data from your *own* Intercom app

If you want to build an integration to access other people's Intercom data, you will need to use OAuth.

Standard Scopes

Standard scopes should provide everything you need to get up and running quickly:

Scope
Description

Write users and companies

Create and update users and companies. Also allows execution of bulk actions on users and Leads.

Write tags

Create, update, use and delete tags

Write events

Submit events (i.e. user activity)

Write conversations

Reply to, mark as read and close conversations

Read one user and one company

List and view a single user, lead or company

Read one admin

View a single admin

Read events

List all events belonging to a single user

Read tags

List all tags

Read counts

Count users and companies with specified criteria

If you think you need more permissions, you can apply for extended scopes.

HTTP 401 "UNAUTHORIZED"

Note that if you have standard scopes and you see this error you may need to apply for extended scopes. You will see this error if you are attempting to use a resource that is only allowed via the extended scopes permissions.

Extended Scopes

Requests for extended scopes require review by our team - most are approved within 24 hours. You’ll be able to use standard scopes in the meantime.

To ensure that these scopes are being implemented correctly you'll be asked to provide a brief description of why you need the extended scopes.

Extended scopes include:

Scopes
Description

Read and list users and companies

List and view all segments, users and companies

Read conversations

View conversations

Read admins

List and view all admins

Manage webhooks

Create and update webhooks

You can update your request at any time

If you're unsure which scopes you need, we recommend applying for standard scopes first – you can come back and request extended scopes at any time if you find you need them.

Your Token will not change and will be valid with standard permissions while you are awaiting approval for the extended scopes.

Using your Access Token

Once you have created your Access Token you will see it in the same section in your Dashboard. You can edit or delete the token from here.

You can copy your token and use it in in much the same way as you would use an API Key. The specifics will depend on how you are integrating with Intercom – i.e. whether you are using curl or a particular client library. For example, using curl the difference is as follows:

$ curl \
-s https://api.intercom.io/users/5321a20f72cdbb4192000013 \
-u <APP ID>:<API KEY> \
-H 'Accept:application/json'

The Token can then be used as the 'username' for the Basic Auth flow. You can leave the password blank. Refer to the specific client library for more info on how to use the Token.

$ curl \
-s https://api.intercom.io/users/5321a20f72cdbb4192000013 \
-u '<PAT>': -H 'Accept:application/json'

Create an Access Token