Applying for OAuth

📘

What you need before getting started

The only thing you need to setup OAuth is an Intercom account. If you're already signed up, great!

If not, then just follow the instructions here to sign up for a free trial of Intercom. For more detailed information on the different products and pricing options available you can check out our pricing page.

Get started instantly

We know you want to get started developing your integration as quickly as possible, so we've made it possible to get instant OAuth approval for your test app so you can start building right away.

You'll only need to go through an approval process once you're ready to put your integration into production.

The whole process looks like this:

1. Create a TEST Intercom app
2. Get OAuth for your TEST app instantly
3. Build your integration in your TEST app
4. When you're ready to make your integration live, apply for OAuth approval for your main Intercom app with a short demo video
5. We'll review your application, usually within 5-10 working days

You'll find full instructions for each step below.

🚧

Remember you only need OAuth if you're building an integration you want others to be able to use. If you're just building for yourself, you can use Access Tokens instead.

1. Create a TEST Intercom app

To start building an integration, you first need to set up a TEST Intercom app. Setting up your TEST environment in Intercom is as simply as ticking a box in your main production app settings page:

You can find all the setup details here along with more detail on how to use the Intercom TEST version.

📘

TEST v Main Intercom app

The main difference between your TEST and main app is that the TEST app limits OAuth access to your Intercom teammates – you can't request OAuth access from someone that it not a teammate in your TEST app. In order to do so, you'll need to go through the approval process to get OAuth approval in your main Intercom app (once you're ready to make your integration live).

You must setup your integration in your TEST app first; we will not approve OAuth applications for main apps without this step.

2. Get OAuth access instantly

Once you have created your TEST app you can get OAuth access immediately by applying for OAuth from your TEST app. You can apply here or by going to 'settings' within the Intercom app menu (hover over your avatar on the bottom left) and then clicking on the 'app settings' tab > 'developer tools' > 'OAuth'. If you would like to more details about the application form itself and have question about each field then you can take a look at the "Registering your app" section in our setup guide. This guide has more information on how to setup OAuth once you have received OAuth approval.

📘

Need additional permissions?

While working on your integration you might discover that you need additional permissions or you need to change the redirect URL. You can simply update your OAuth application from your TEST app and it will update instantly.

Only apply for permissions you actually need – otherwise your approval for your main app may be denied or delayed.

🚧

What if I just apply for OAuth from my production app?

For any integration, we require you to apply via your TEST app first.

Note that this also includes any integrations migrating from using API keys to OAuth. Any applications for OAuth without first applying via a TEST app will be rejected.

3. Build your integration

You can find everything you need to build your integration right here in our developer hub, including tutorials and our API reference. The first thing you might need after getting auto approval is details of how to setup the OAuth flow itself. You can find the steps and a worked example here. If you need any help, just send us a message 😀

4. Apply for OAuth approval for your main Intercom app

Once you're happy that your integration is ready, you need to apply for OAuth approval for your main Intercom app so that you can accept users outside of your own app.

For this, you'll need to put together a short demo video for our team to review. This video should clearly show the OAuth setup flow. Alongside the video, you should also provide reasons for the scopes you need.

Send these to us via the messenger by replying to the OAuth approval message you will have received when you applied with your TEST app. Make sure the video is in a downloadable format, so that we can keep it for future reference (we will never share your video with anyone else without your approval).

5. We'll review your application

We'll review your video and get back to you as soon as we can. We manually review all applications in the order they come in, so it can take 5-10 working days for us to get back to you.

You'll receive a reply to your message letting your know if your application has been approved or denied.

If you're denied approval
We take our customers' experience and data security seriously, so we sometimes deny OAuth approval if we feel that these are not being met to a high enough standard.

Every case is different, but some examples why your application may be denied include:

• The setup flow is non-functional or broken
• There is a risk to the security of a user's data
• You're using old Intercom logos or misusing our branding in some way
• You're requesting too many permissions you don't need

If your application is denied, we will provide you with a reason for this and any actions you can take before re-applying.

More tips and advice

Read our developer guidelines

By integrating with Intercom or using our API, you are agreeing to abide by our developer guidelines so you should be sure to read them.

Read our integration guidelines

Take a few minutes to checkout our integration guidelines. We use these when evaluating your integration so it's worth ensuring you're following them to increase the chances of your application being approved.

Don't be greedy with permissions

Apply only for the permissions you need – if you're unsure you can always update your TEST app whenever you need more permissions. This is important when you apply for your main production app as if it isn't clear why you need all the permissions you've applied for, your approval will be delayed or denied.

No old Logos ... please!

Please, please, please ... do not use old Intercom logos or misrepresent our branding, even on your TEST app. This makes us very sad and is a sure fire way to delay your OAuth application. You can find our latest logos and other resources here