Intercom API Developer Docs


Search results for "{{ search.query }}"

No results found for "{{search.query}}".

OAuth vs. Personal Access Tokens

Note: Personal Access Tokens and OAuth have replaced API Keys

If you are currently using API Keys, you will need to switch to using either Personal Access Tokens or OAuth by January 2017 - read more about API Key deprecation here.

In order to authorize access to your own or other people's data in Intercom, you will need to have either Personal Access Tokens or OAuth.

Which of these you use depends on your use case:

  • Personal Access Tokens: if you're using the API to access your own Intercom data

  • OAuth: if you're building a publicly-available integrations 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 Personal Access Tokens or OAuth while your API Keys are still active to ensure that there is no disruption to your current service. You can then switch from your API Keys to your new method at any time before your API Keys are deprecated in Jan 2017.

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.

When to use Personal Access Tokens

You should use a Personal 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

Personal Access Token Flow

Setting up Personal Access Tokens

If the description above matches your use case then you can simply use a Personal Access Token (which will replace your API Keys if you're currently using these). Setting up a Personal Access Token is simple and instant if you only require standard scopes - find out how to set up here.

Need help?

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

OAuth vs. Personal Access Tokens