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

Aug 13, 2024 • 6 minute read

Hey there, fellow JavaScript enthusiasts! Ready to dive into the world of Linear integrations? Today, we're going to walk through building a rock-solid auth flow for your Linear integration. Buckle up, because we're about to make your app a whole lot more powerful!

Prerequisites

Before we jump in, let's make sure we're on the same page. I'm assuming you're already familiar with:

Linear API basics
OAuth 2.0 fundamentals
Your favorite JavaScript framework

Got all that? Great! Let's get started.

Setting up the Linear OAuth Application

First things first, we need to set up our Linear OAuth app. Head over to the Linear developer portal and create a new OAuth app. You'll get a client ID and secret – keep these safe, you'll need them soon!

Implementing the Authorization Flow

Alright, here's where the magic happens. We're going to break this down into three main steps:

Initiating the auth request

Let's construct that authorization URL:

const authUrl = `https://linear.app/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&response_type=code&scope=${scope}&state=${state}`;

Now, redirect your user to this URL. They'll see Linear's auth page and can grant your app permissions.

Handling the callback

Once the user approves, Linear will redirect them back to your redirect_uri with an authorization code. Grab that code from the URL:

const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');

Now, exchange this code for an access token:

const response = await fetch('https://api.linear.app/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: clientId,
    client_secret: clientSecret,
    redirect_uri: redirectUri,
    code: code,
  }),
});

const { access_token, refresh_token } = await response.json();

Storing and managing tokens

Store these tokens securely. Never expose them client-side – keep them safe on your server!

Making Authenticated Requests

Now that you've got your access token, you can make authenticated requests to Linear's API:

const response = await fetch('https://api.linear.app/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: '{ viewer { id name } }' }),
});

Don't forget to handle token expiration and refresh when needed!

Best Practices

Always use HTTPS
Implement proper error handling
Respect Linear's rate limits
Regularly rotate your client secret

Testing the Integration

Test your auth flow thoroughly. Try different scenarios:

Happy path (everything works)
User denies permission
Token expiration and refresh

If you run into issues, double-check your redirect URIs and scopes.

Conclusion

And there you have it! You've just built a solid auth flow for your Linear integration. With this foundation, you can now tap into Linear's powerful API and build some truly awesome features.

Remember, the key to a great integration is a smooth user experience and rock-solid security. Keep iterating, keep improving, and most importantly, keep building cool stuff!

Resources

Happy coding, and may your commits always be clean and your PRs always be approved! 🚀