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 5 days. 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'
Updated over 6 years ago