Pipes – WorkOS Docs

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.