Pipes
Let your users connect their GitHub, Google, Slack, Salesforce and other accounts, and get fresh access tokens on your server.
Pipes handles third-party OAuth connections for your end users. When your app needs to call GitHub, Google, Slack or another API on a user’s behalf, Pipes runs the connect flow, stores the tokens encrypted, refreshes them and hands your server a fresh access token when you ask.
Providers
Section titled “Providers”Built-in providers: github, google, slack, salesforce, hubspot, linear and notion, plus oauth2 for any other OAuth 2.0 provider (give its authorize_url, token_url and optional revoke_url). Configure each with your own OAuth app: PUT / with kind, client_id, client_secret and scopes. Register https: as the redirect URI in the provider’s console. Using a provider that is not set up answers pipe_provider_not_configured.
While any of a provider’s connections is connected, its authorize, token and revoke endpoint hosts, and so its kind, cannot change: stored tokens must never be sent to a new host. Such a PUT answers pipe_provider_has_connections (409). The client ID, secret and scopes can still change. To move to new endpoints, configure them under a new provider slug and have users reconnect, or disconnect the provider’s connections first.
Connect a user
Section titled “Connect a user”- Your server calls
POST /withv1/ pipes/ connections provider,organization_id, youruser_idand areturn_url. Scope:pipes:write. - Redirect the user’s browser to the
connect_urlin the answer, from their own signed-in session in your app. It expires atexpires_at. - The user approves at the provider. OhAuthCat completes the code exchange with PKCE and a single-use state, then returns the browser to your
return_url. - You receive
pipe.(orconnection. connected pipe.connection.failed).
The connect_url is bound to the first browser that opens it, with a short-lived cookie scoped to /pipes. A later visit, or the provider’s callback, from any other browser answers pipe_connect_browser_mismatch (403) and the flow stays unused. So:
- Send
connect_urlonly as a redirect inside the end user’s own signed-in session. Never email it, post it in chat or show it to anyone else: whoever opens it first owns the flow. - If the user hits the error, for example because a link preview opened the URL first, create a new connection flow and redirect them again.
Use the connection
Section titled “Use the connection”GET / returns a current access_token, refreshing it first when needed. Refresh tokens are rotated under a lock, so concurrent calls do not race. The response must not be cached. If the user has disconnected or the refresh failed, the call answers pipe_connection_not_connected.
DELETE / disconnects and revokes the tokens at the provider when it supports revocation (pipe.). GET / lists connections by organization, user or provider; the CLI equivalent is ohauthcat pipes connections list.
Token response details differ between providers. Each built-in provider has passed tests against a simulated provider; behaviour against each live provider is still being checked.