Note: Access Tokens and OAuth have replaced API Keys
To access the Intercom API, whether it's to access your own team's data or other people's Intercom data (for example through an integration), you will need a token.
Which type of token you need depends on your use case:
- Use Access Tokens: if you're using the API to access data in your own Intercom app
- Use OAuth: if you're building a publicly-available integration that accesses other people's Intercom data
If you're unsure, use the guide below to work out which you need.
Switching from API Keys?
If you're switching from API Keys, you can set up Access Tokens or OAuth while your API Keys are still active to ensure that there is no disruption to your current service.
You should use OAuth if:
- You are requesting access to other people's Intercom accounts/data (for example, through an integration you've built)
- You currently ask people for their API Keys to request resources on their behalf
- You want to make it easier for your customers to share their customers' data with you
If the OAuth description above describes your current use case then you will need to follow the Intercom OAuth flow. To do this you will need to follow the steps here to receive your OAuth token, which will allow you to request resources on behalf of your users. You will then be able to use your token as outlined in the relevant client library you are using.
Remember to also update any setup documentation you have for users to reflect this new flow.
Never ask users for their Access Token
Asking your users of your integration for their Access Tokens rather than implementing OAuth is against our terms of service and may result in your API access being revoked.
You should use an Access Token if:
- You want to use the API to interact with your own Intercom App
- You have scripts to push or extract data from your Intercom App
- You want to use the API to programmatically automate certain actions in your own Intercom app
- The data you interact with programmatically is your own customer data
Access Tokens Flow
If the description above matches your use case then you can simply use an Access Token (which will replace your API Keys if you're currently using these). Setting up an Access Token is simple and instant if you only require standard scopes - find out how to set it up here.
Never give your Access Token to a third party
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.
Take a look at our FAQ or just send us a message and we'll be happy to help.