{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Authentication","projectTitle":"Intercom and Fin Developer Platform","description":"Faster resolutions, higher CSAT, and lighter support volumes with the only platform to combine the power of automation and human customer support.","siteUrl":"https://developers.intercom.com","image":"/assets/og-image.9c9ef3a6cedbceee0e1d52fae2ffcce97f5a189639cf24e473331da9ad02c5f8.b1bff462.png","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To access the Intercom API, you have two authentication options depending on whether you app is public or private."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#access-tokens"},"children":["Access Token"]}," is for if you're using the API to access data in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["your own"]}," Intercom workspace, in other words, building a private app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#oauth"},"children":["OAuth"]}," is for if you're building a public app that accesses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["other people's"]}," Intercom data."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"access-tokens","__idx":1},"children":["Access Tokens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access Tokens can be used for the following cases:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to use the API to build a private Intercom app"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to run scripts to create or get data from your Intercom workspace"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to use the API to programmatically automate certain actions in your Intercom workspace"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all of these cases, the data you are accessing is your own team's customer data."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/pat-flow.a57707b73af31a3ae69f2b18a4c0ce9d8341d659a8649917e833232025570ed9.71a4f21c.png","alt":"A image showing the use of a personal access token to work with data on the Intercom API"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-to-get-your-access-token","__idx":2},"children":["How to get your Access Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We provide you with an Access Token as soon as you ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.intercom.com/admins/sign_up/developer"},"children":["create an app"]}," on your workspace."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find your Access Token in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configure > Authentication"]}," section in your app within the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.intercom.io/a/apps/_/developer-hub/app-packages"},"children":["Developer Hub"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/e77cdff-access_token.4c1ae57393655175c1f2455f5ec4052968f3788fdef7cbccd1e74cae1baa7b9f.71a4f21c.png","alt":"Access Token"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also visible on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test & Publish > Your Workspaces"]}," page. This displays workspaces that have the app installed. More about how this works can be found in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/build-an-integration/learn-more/authentication/installing-uninstalling-apps"},"children":["Installing & Uninstalling Apps guide"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Never give your Access Token to a third-party"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"oauth","__idx":3},"children":["OAuth"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You should use OAuth if:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You are requesting access to other people's Intercom accounts/data (for example, through an integration you've built)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You currently ask people for their API Keys to request resources on their behalf"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want to make it easier for your customers to share their customers' data with you"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/x8kdkklsq424lxuz7sh1_oauth_cropped.72b26d1b307b50411b414a8f33759513922c6d65806be67a4eb92a896617e841.71a4f21c.png","alt":"OAuth Flow","title":"OAuth Flow"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getting-started-with-oauth","__idx":4},"children":["Getting Started with OAuth"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To set up and test the OAuth installation flow in your development workspace by ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/build-an-integration/learn-more/authentication/setting-up-oauth"},"children":["following this tutorial"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Never ask users for their Access Token"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-to-use-the-token","__idx":5},"children":["How to use the token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have a token, whether an access token or a token via the OAuth process, simply provide it as an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization:Bearer"]}," header in your requests, as shown below. If you want to go deeper on how the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization:Bearer"]}," header works please check out the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tools.ietf.org/html/rfc6750"},"children":["full spec here"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"$ curl \\\n-s https://api.intercom.io/users/5321a20f72cdbb4192000013 \\\n-H 'Authorization:Bearer <access_token>' \\\n-H 'Accept:application/json'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"intercom = Intercom::Client.new(token: '<access_token>');\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"{\"token\": '<access_token>'}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"var client = new Intercom.Client({ token: '<access_token>' });\n","lang":"javascript"},"children":[]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"Access Tokens","id":"access-tokens","depth":2},{"value":"How to get your Access Token","id":"how-to-get-your-access-token","depth":3},{"value":"OAuth","id":"oauth","depth":2},{"value":"Getting Started with OAuth","id":"getting-started-with-oauth","depth":3},{"value":"How to use the token","id":"how-to-use-the-token","depth":2}],"frontmatter":{"seo":{"title":"Authentication"}},"lastModified":"2025-11-27T13:37:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/build-an-integration/learn-more/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}