Skip to content
Dashboard
Theme
Theme

Pipes

Let your users connect their GitHub, Google, Slack, Salesforce and other accounts, and get fresh access tokens on your server.

View Markdown

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.

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 /v1/pipes/providers/{provider} with kind, client_id, client_secret and scopes. Register https://api.ohauthcat.com/pipes/callback 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.

  1. Your server calls POST /v1/pipes/connections with provider, organization_id, your user_id and a return_url. Scope: pipes:write.
  2. Redirect the user’s browser to the connect_url in the answer, from their own signed-in session in your app. It expires at expires_at.
  3. 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.
  4. You receive pipe.connection.connected (or 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_url only 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.

GET /v1/pipes/connections/{connection}/access_token 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 /v1/pipes/connections/{connection} disconnects and revokes the tokens at the provider when it supports revocation (pipe.connection.disconnected). GET /v1/pipes/connections 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.