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 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'.
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.
Write users and companies
Create and update users and companies. Also allows execution of bulk actions on users and Leads.
Create, update, use and delete tags
Submit events (i.e. user activity)
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
List all events belonging to a single user
List all tags
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.
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:
Read and list users and companies
List and view all segments, users and companies
List and view all admins
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.
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'