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

Hey there, fellow JavaScript enthusiast! Ready to dive into the world of Bloomerang integrations? Let's roll up our sleeves and build a rock-solid auth flow that'll make your users feel like they're in Fort Knox (but with better UX).

The Lowdown on Bloomerang and Auth

Bloomerang's a powerhouse for nonprofit CRM, and integrating with it can open up a world of possibilities. But before we can play with all that juicy data, we need to get our auth game on point. Trust me, a secure auth flow is like a good cup of coffee – essential and energizing.

Before We Jump In

Make sure you've got:

• Your Bloomerang API credentials (if you don't have 'em, go grab 'em!)
• A Node.js environment with Express.js ready to rock

Got all that? Awesome. Let's get this party started!

OAuth 2.0: Your New Best Friend

We're using OAuth 2.0's Authorization Code Grant. It's like a secret handshake, but way cooler and more secure. Here's the gist:

1. We ask Bloomerang for permission
2. User says "yes, please!"
3. We get a special code
4. We trade that code for access tokens

Simple, right? Let's break it down.

Kicking Off the Auth Dance

First up, we need to construct that authorization URL. It's like crafting the perfect pick-up line, but for APIs:

const authUrl = `https://crm.bloomerang.co/authorize?
  response_type=code&
  client_id=${YOUR_CLIENT_ID}&
  redirect_uri=${encodeURIComponent(REDIRECT_URI)}&
  scope=constituent`;

res.redirect(authUrl);

Make sure your REDIRECT_URI is set up in your Bloomerang app settings. It's where the magic happens next.

Catching the Auth Code

When Bloomerang redirects back to you, it's bringing gifts! Set up a route to catch that sweet, sweet auth code:

app.get('/callback', (req, res) => {
  const { code, error } = req.query;
  if (error) {
    // Uh-oh, something went wrong. Handle it gracefully!
    return res.status(400).send(`Auth error: ${error}`);
  }
  // You've got the code! Now, let's trade it for tokens.
});

Token Time: The Grand Exchange

Now, let's swap that code for some shiny new tokens:

const tokenResponse = await axios.post('https://crm.bloomerang.co/token', {
  grant_type: 'authorization_code',
  code,
  redirect_uri: REDIRECT_URI,
  client_id: YOUR_CLIENT_ID,
  client_secret: YOUR_CLIENT_SECRET
});

const { access_token, refresh_token } = tokenResponse.data;

Boom! You've got tokens. Treat them like your most prized possessions.

Keeping Those Tokens Fresh

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

const refreshTokens = async (refreshToken) => {
  const response = await axios.post('https://crm.bloomerang.co/token', {
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
    client_id: YOUR_CLIENT_ID,
    client_secret: YOUR_CLIENT_SECRET
  });
  return response.data;
};

User Sessions: Keeping It Personal

Associate those tokens with your user's session. Here's a quick and dirty way:

req.session.bloomerangTokens = { access_token, refresh_token };

And when you need to make authenticated requests:

const makeAuthenticatedRequest = async (url) => {
  const { access_token } = req.session.bloomerangTokens;
  return axios.get(url, {
    headers: { Authorization: `Bearer ${access_token}` }
  });
};

When Things Go South: Error Handling

APIs can be moody. Be prepared:

try {
  // Your API call here
} catch (error) {
  if (error.response && error.response.status === 401) {
    // Time to refresh that token!
  } else {
    // Handle other errors
  }
}

Taking It for a Spin

Before you ship it, give it a whirl:

1. Start your auth flow
2. Log in to Bloomerang
3. Check if you get the tokens
4. Try making an authenticated request

Pro tip: Set up some automated tests. Your future self will thank you.

Locking It Down: Security Best Practices

• Always use HTTPS. Always.
• Implement the state parameter to prevent CSRF attacks.
• Store tokens securely. No plaintext shenanigans!

You Did It!

And there you have it! You've just built a solid auth flow for your Bloomerang integration. Pat yourself on the back – you've earned it.

Remember, this is just the beginning. Now that you've got the keys to the kingdom, the real fun begins. Go forth and build something awesome!

Happy coding, and may your API calls always return 200 OK! 🚀