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

Aug 17, 2024 • 6 minute read

Hey there, fellow JavaScript enthusiasts! Ready to dive into the world of Recruitee integrations? Today, we're going to walk through building a rock-solid authorization flow for your public Recruitee integration. Buckle up, because we're about to make your integration secure and user-friendly!

Introduction

Recruitee's API is a powerful tool for building integrations, but let's face it - security is paramount. We're talking about sensitive recruitment data here, so we need to make sure our auth flow is tighter than a drum. Don't worry, though; with OAuth 2.0, we've got this covered.

Prerequisites

Before we jump in, make sure you've got:

Your Recruitee API credentials (you'll need these, trust me)
A Node.js environment with Express.js set up (because who doesn't love Express, right?)

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

OAuth 2.0 Flow Overview

We're using the Authorization Code Grant type here. It's like the VIP pass of OAuth flows - secure and perfect for server-side apps. You'll need three key things:

Client ID (your app's unique identifier)
Client Secret (keep this one close to your chest)
Redirect URI (where Recruitee will send the user after authorization)

Implementing the Authorization Flow

Initiating the Auth Request

First things first, let's get that authorization URL set up:

const authUrl = `https://app.recruitee.com/o/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&response_type=code`;

Now, when your user wants to connect, just redirect them to this URL. Easy peasy!

Handling the Callback

Set up an endpoint to handle the redirect. This is where the magic happens:

app.get('/callback', async (req, res) => {
  const { code } = req.query;
  // We'll use this code in the next step
});

Exchanging Code for Access Token

Time to trade that code for an access token:

const tokenResponse = await axios.post('https://app.recruitee.com/o/oauth/token', {
  client_id: clientId,
  client_secret: clientSecret,
  code,
  grant_type: 'authorization_code',
  redirect_uri: redirectUri
});

const { access_token, refresh_token } = tokenResponse.data;

Store these tokens securely. They're your golden tickets!

Refreshing the Access Token

Access tokens don't last forever. When they expire, use the refresh token to get a new one:

const refreshTokenResponse = await axios.post('https://app.recruitee.com/o/oauth/token', {
  client_id: clientId,
  client_secret: clientSecret,
  refresh_token: storedRefreshToken,
  grant_type: 'refresh_token'
});

Making Authenticated Requests

Now you're ready to make API calls. Just include the access token in your requests:

const response = await axios.get('https://api.recruitee.com/c/12345/candidates', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

If you get a 401, it's probably time to refresh that token!

Security Considerations

Listen up, because this part's crucial:

Always use HTTPS. Always.
Store tokens securely. No plaintext storage, please!
Implement CSRF protection. Security is a full-time job.

Testing the Auth Flow

Before you pop the champagne, make sure to test thoroughly:

Try the full flow manually
Set up some automated tests (your future self will thank you)

Conclusion

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

Remember, the auth flow is just the beginning. Now you can start building out those awesome features you've been dreaming of. The Recruitee API is your oyster!

Additional Resources

Want to dive deeper? Check out:

Now go forth and integrate! And remember, with great power comes great responsibility. Use those API calls wisely!