Pipes

Configure a provider in the WorkOS Dashboard to make it available to your users.

Visit the Pipes section of the WorkOS Dashboard. Click Connect provider and choose the provider from the list. If you do not see the provider you need, reach out to our team.

Use WorkOS-managed shared credentials in sandbox environments for the fastest setup. 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.

Configure the provider with your own OAuth credentials for production applications:

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.

Use the Pipes Widget to give users a pre-built UI for connecting and managing their accounts. The widget shows available providers and lets users initiate the authorization flow. It communicates with the WorkOS API and stores the connection information for the user. If a problem occurs with the user’s access token, the widget notifies them to reauthorize.

After a user connects a provider, fetch access tokens from your backend to make API calls to the connected service on their behalf. Pipes handles token refreshing automatically, so you always receive a fresh token. If a problem occurs with the token, the endpoint returns information about the issue so you can direct the user to correct it. This may require sending the user to reauthorize 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;
}