Pipes

Pipes allows your users to securely connect their third-party accounts to your application. With Pipes, you can easily integrate with popular services like GitHub, Slack, Google, Salesforce, and many more without managing OAuth flows, token refresh logic, or credential storage.

To make an provider available to your users, you will need to configure it in the WorkOS Dashboard.

Visit the Pipes section of the WorkOS Dashboard to get started. Click Connect provider then choose the provider from the list. If you don’t see the provider you need, please reach out to our team.

For the fastest setup, you can use WorkOS-managed shared credentials in sandbox environments. This allows users to connect immediately without requiring you to create OAuth applications with each provider.

1. Specify the required scopes for your application.
2. Provide an optional description. This will be used in the widget to inform users on how your application will use their data from the provider.

For production applications, configure the provider with your own OAuth credentials:

1. Create an OAuth application within the provider’s dashboard.
   1. You can find instructions on setting up the provider in the documentation section of the setup modal.
2. Use the provided redirect URI when configuring the provider.
3. Set the client ID and secret from the provider.
4. Specify the required scopes for your application.
   1. You may need to set these scopes in the provider configuration as well.
5. Provide an optional description. This will be used in the widget to inform users on how your application will use their data from the provider.

Commonly used scopes are provided in-line, but you should consult each provider’s documentation for the full list of available scopes.

The Pipes Widget provides a pre-built UI for users to connect and manage their connected accounts. The widget shows the user which providers are available, and lets them easily initiate the authorization flow. It communicates with the WorkOS API and stores the connection information for the user. If there’s ever a problem with the user’s access token, the widget will let them know they need to reauthorize.

Once a user has connected a provider, you can fetch access tokens from your backend to make API calls to the connected service on their behalf. Pipes takes care of refreshing the token if needed, so you’ll always have a fresh token. If there’s a problem with the token, the endpoint will return information about the issue so you can direct the user to the correct it. This may require sending the user to re-authorize directly or via the page with the Pipes widget.

import { Octokit } from '@octokit/rest';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

async function getUserGitHubRepos(userId, organizationId) {
  const { accessToken, error } = await workos.pipes.getAccessToken({
    provider: 'github',
    userId: userId,
    organizationId: organizationId,
  });

  if (!accessToken) {
    // Handle error: user needs to connect or reauthorize
    console.error('Token not available:', error);
    return;
  }

  // Check if required scopes are missing
  if (accessToken.missingScopes.includes('repo')) {
    console.error('Missing required "repo" scope');
    return;
  }

  // Use the access token with GitHub API
  const octokit = new Octokit({
    auth: accessToken.token,
  });

  const { data: repos } = await octokit.repos.listForAuthenticatedUser();

  return repos;
}