How to build a public Process Street integration: Building the Auth Flow

Introduction

Hey there, fellow developers! Ready to dive into the world of Process Street integrations? Today, we're going to tackle one of the most crucial aspects of building a public integration: the authorization flow. Process Street's API is powerful, but without proper authorization, it's like having a sports car without the keys. Let's change that!

Prerequisites

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

• Node.js and npm installed (you're a JavaScript dev, so I'm sure you've got this covered)
• A basic understanding of OAuth 2.0 (don't worry, we'll refresh your memory)
• Process Street API credentials (if you don't have these yet, hop over to their developer portal)

Setting up the project

Let's get our project off the ground:

mkdir process-street-integration
cd process-street-integration
npm init -y
npm install express axios dotenv

Great! Now we've got the basics set up. Let's create an index.js file and get coding!

Implementing OAuth 2.0 Authorization Code Flow

OAuth 2.0 might sound intimidating, but it's just a fancy way of saying "let's make sure the right people have access to the right stuff." Here's how we'll break it down:

Create authorization URL

First, we need to send users to Process Street to grant permissions:

const authUrl = `https://app.process.st/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=read,write`;

Handle authorization callback

Once the user grants permission, Process Street will redirect them back to your app with a code. Let's catch that:

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

Exchange authorization code for access token

Now, let's swap that code for an access token:

const tokenResponse = await axios.post('https://app.process.st/oauth/token', {
  grant_type: 'authorization_code',
  code,
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uri: REDIRECT_URI
});

const { access_token, refresh_token } = tokenResponse.data;

Store and manage access tokens

You'll want to store these tokens securely. For now, let's keep it simple:

// This is just an example. In a real app, use a secure database!
const tokens = { access_token, refresh_token };

Building the authorization endpoints

Let's set up our Express app to handle these flows:

const express = require('express');
const app = express();

app.get('/auth', (req, res) => {
  res.redirect(authUrl);
});

app.get('/callback', async (req, res) => {
  // Handle the callback as we discussed earlier
});

app.get('/refresh', async (req, res) => {
  // Implement token refresh logic here
});

Securing the integration

Security isn't just a buzzword, it's our bread and butter. Let's add some extra layers:

Implement PKCE

PKCE adds an extra layer of security. Here's a quick implementation:

const crypto = require('crypto');

function generateCodeVerifier() {
  return crypto.randomBytes(32).toString('hex');
}

function generateCodeChallenge(verifier) {
  return crypto.createHash('sha256').update(verifier).digest('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

Validate state parameter

Always validate the state to prevent CSRF attacks:

app.get('/callback', (req, res) => {
  if (req.query.state !== savedState) {
    return res.status(400).send('Invalid state parameter');
  }
  // Proceed with token exchange
});

Making authenticated API requests

Now that we're authorized, let's make some API calls:

const response = await axios.get('https://api.process.st/v1/workflows', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});

Remember to handle rate limits and errors gracefully. Process Street's API is friendly, but it's not a pushover!

Best practices

• Error handling: Always expect the unexpected. Wrap your API calls in try/catch blocks.
• Logging: Log important events, but be careful not to log sensitive information.
• Token refresh: Set up a system to refresh tokens before they expire. Your future self will thank you.

Testing the integration

Manual testing is great, but automated tests are even better. Consider setting up Jest or Mocha to run through your authorization flow automatically.

Conclusion

And there you have it! You've just built a secure authorization flow for your Process Street integration. Remember, this is just the beginning. There's a whole world of workflows and checklists waiting for you to integrate with.

Keep exploring, keep building, and most importantly, keep making those processes street-smart! Happy coding!