How to build a public Intercom integration: Building the Auth Flow

Aug 11, 2024 • 7 minute read

Hey there, fellow JavaScript enthusiasts! Ready to dive into the world of Intercom integrations? Today, we're going to tackle one of the most crucial aspects of building a public integration: the authorization flow. Buckle up, because we're about to make your integration secure and user-friendly in no time!

The Lowdown on Intercom Integration

Before we jump in, let's quickly touch on why we're here. Intercom is a powerful customer communication platform, and by building an integration, you're opening up a world of possibilities for your users. But remember, with great power comes great responsibility – that's where our secure authorization flow comes in.

What You'll Need

Alright, let's make sure you've got all your ducks in a row:

An Intercom Developer account (if you don't have one, go grab it!)
A solid grasp on OAuth 2.0 (don't worry, we'll refresh your memory)
Node.js and Express.js set up and ready to roll

Got all that? Great! Let's get this show on the road.

Setting Up Your Intercom App

First things first, head over to the Intercom Developer Hub and create your app. It's pretty straightforward, but pay extra attention to the OAuth settings. You'll need to set your redirect URI – this is where Intercom will send your users after they've authorized your app.

Once you're done, you'll get your client ID and client secret. Guard these with your life (or at least, keep them super secure)!

Building the Authorization Flow

Now for the main event! Let's break this down into manageable chunks:

Step 1: Kick Off the OAuth Process

We'll start by creating an authorization URL. It'll look something like this:

const authUrl = `https://app.intercom.com/oauth?client_id=${clientId}&redirect_uri=${redirectUri}`;

When your user wants to connect their Intercom account, send them to this URL. They'll log in to Intercom and give your app the thumbs up.

Step 2: Handle the Callback

Once the user approves your app, Intercom will redirect them back to your specified redirect URI with an authorization code. Time to exchange that for an access token!

app.get('/callback', async (req, res) => {
  const { code } = req.query;
  const tokenResponse = await axios.post('https://api.intercom.io/auth/eagle/token', {
    code,
    client_id: clientId,
    client_secret: clientSecret,
  });
  
  // Store the access token securely
  const { access_token } = tokenResponse.data;
  // ... store the token ...
});

Step 3: Store and Manage Tokens

Now that you've got the access token, store it securely. You might want to encrypt it before saving it to your database. Also, don't forget to implement a refresh mechanism – tokens don't last forever!

Making Authenticated Requests

With your shiny new access token, you're ready to start making requests to Intercom's API. Here's a quick example:

const userData = await axios.get('https://api.intercom.io/me', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Intercom-Version': '2.8',
  },
});

Handling Errors and Edge Cases

Things don't always go according to plan, so make sure you're prepared:

Check for expired tokens before making requests
Implement proper error handling for authorization failures
Have a plan for when users revoke access to your app

Keeping It Secure

Security isn't just a feature, it's a necessity. Here are some tips:

Never, ever expose your client secret
Always use HTTPS
Implement CSRF protection to prevent malicious requests

Testing Your Integration

Before you pop the champagne, make sure everything's working smoothly:

Test the full authorization flow manually
Set up automated tests for different scenarios
Try to break your own system (better you than a user, right?)

Wrapping Up

And there you have it! You've just built a secure authorization flow for your Intercom integration. Pat yourself on the back – you've taken a big step towards creating a powerful, user-friendly integration.

Remember, this is just the beginning. There's a whole world of Intercom API endpoints to explore and features to implement. So go forth and integrate!