OAuth vs. Access Tokens

🚧

Note: Access Tokens and OAuth have replaced API Keys

As of April 2017, all public integrations must use OAuth rather than API Keys.

If you're using an API Key to access the Intercom API for your own data, you should switch to using an Access Token asap - API Keys will be fully deprecated in early 2018.

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.

When to use OAuth

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

OAuth Flow

Setting up OAuth

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.

When to use Access Tokens

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

Setting up Access Tokens

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.

Need help?

Take a look at our FAQ or just send us a message and we'll be happy to help.