Authentication

Introduction

To access the Intercom API, you'll need an access token. How you get this token depends on if your app is for your own usage or for the public's usage.

• Use the given Access Token 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 the given access 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

How to get your Access Token

We provide you with an Access Token as soon as you create an app on your workspace. You can find your Access Token in the Configure > Authentication section in your app within the Developer Hub.

You will also see it in your Test & Publish > Your Workspaces page of your app in the Developer Hub. This lists out all of your workspaces that have the app installed. More about how this works can be found in our Installing & Uninstalling Apps guide.

❗️

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

Getting Started with OAuth

To set up and test the OAuth installation flow we recommend using a development workspace. For more information on how to set up OAuth please follow our tutorial.

❗️

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 the token

Once you have a token, whether an access token or a token via the OAuth process, simply provide it as an Authorization:Bearer header in your requests, as shown below. If you want to go deeper on how the Authorization:Bearer header works please check out the full spec here.

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

Alternatively, helper functions are provided 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>' });