# Pipes

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

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`](/errors/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`](/errors/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

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`](/errors/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.

## Use the connection

`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`](/errors/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.
