Authorization

To access the Intercom API, you'll need a token. The 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 workspace.
  • Use OAuth if you're building a publicly-available app that accesses other people's Intercom data.

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 Token Flow

Access Token Flow

How to get an Access Token

We provide an Access Token as soon as you create an app on your workspace.

Find your access token in the Authentication section of your Developer Hub through this link.

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 app provider asks you for your Access Token, please do not provide it. Instead, let us know - apps are required to use OAuth rather than asking users for Access Tokens.

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

OAuth Flow

Getting Started with OAuth

Your development workspace can use OAuth with all scopes to setup the flow and test initially.

You can learn how to get this working in our Setting up OAuth section through this link..

Never ask users for their Access Token

Asking your users for their Access Tokens rather than implementing OAuth is against our terms of service and may result in your API access being revoked.

How to use your Token

To use your Token, simply provide it as part of the authorization header when you make a request. Tokens use the bearer authorization header when you make a request. This just means you need to specify the bearer type in the header.

Look at the official spec through this link for more information on the bearer token framework for the official spec.

$ curl \
-s https://api.intercom.io/users/5321a20f72cdbb4192000013 \
-H 'Authorization:Bearer <access_token>' \
-H 'Accept:application/json'

Alternatively, you can always use the help function which is included in some of our SDKs to authorize via Access Tokens. This means you don't need to specify the header explicitly - it's all done under the hood.

intercom = Intercom::Client.new(token: '<access_token>');
{"token": '<access_token>'}
var client = new Intercom.Client({ token: '<access_token>' });

What's Next

Learn how you can set up the OAuth flow in order to gain the token and access other users' data.

Setting up OAuth