Pipes (connected accounts)

Pipes (Cbox\Id\Pipes\) let a signed-in person connect their own account at a third-party service — GitHub, Google, Microsoft 365, Slack, Salesforce, HubSpot, Linear, Notion — so that your app can call that service's API on their behalf. The platform runs the OAuth 2.0 authorization code flow with PKCE, keeps the access and refresh tokens sealed in the token vault, refreshes them before they expire, and hands a fresh access token to an app you have authorised when it asks.

Your app never stores a third-party token. It asks for one when it needs to make a call.

Mental model

Three contracts:

• Contracts\Pipes — configure, update, remove a pipe; grant and revoke apps.
• Contracts\PipeConnections — the connect flow (start → complete), a person's list, and disconnect.
• Contracts\PipeTokens — lease a fresh access token for an app, and refresh.

The provider catalogue

GitHub's endpoints and the vendor names shared with the sign-in catalogue are read from it rather than restated. A pipe is still a separate OAuth client from a sign-in connection: it asks for API scopes and keeps a refresh token, which a sign-in never does.

Per-installation values (Microsoft's tenant, Salesforce's login domain) are parameters with a default and a strict pattern, because they are substituted into an endpoint the client secret is sent to.

Configure a pipe

use Cbox\Id\Pipes\Contracts\Pipes;

$pipe = app(Pipes::class)->configure(
    provider: 'github',
    clientId: 'Iv1.8a61f9b3a7aba766',
    clientSecret: $secretFromGitHub,      // sealed at rest, never returned
    scopes: ['read:user', 'repo'],        // null = the catalogue's defaults
);

// Which of your apps may lease the tokens people connect through it.
app(Pipes::class)->grant($pipe->id, clientId: 'cid_01j9…');

Connect a person's account

Your app owns the browser. Start the flow for the person who is signed in, keep the returned state in their session, redirect, and finish on the callback:

use Cbox\Id\Pipes\Contracts\PipeConnections;
use Cbox\Id\Pipes\ValueObjects\PipeConnectState;

// GET /account/pipes/github/connect
$authorization = app(PipeConnections::class)->start('github', $user->id, route('pipes.callback', 'github'));
session()->put('pipes:github', $authorization->state->toArray());

return redirect()->away($authorization->url);

// GET /account/pipes/github/callback?code=…&state=…
$flow = PipeConnectState::fromMixed(session()->pull('pipes:github'));
$connection = app(PipeConnections::class)->complete($flow, $request->string('state'), $request->string('code'));

complete() checks the state in constant time, exchanges the code with the PKCE verifier only that session holds, and writes the connection for the person and pipe recorded at start, whatever the callback request says. A failure is a PipeConnectFailed with a stable reason: state_mismatch, pipe_unavailable or exchange_failed. Connecting again replaces the tokens in place, which is how a needs_reauth connection becomes active again.

Lease a token

use Cbox\Id\Pipes\Contracts\PipeTokens;

$token = app(PipeTokens::class)->lease('github', $userId, clientId: 'cid_01j9…', purpose: 'list-repos');

Http::withToken($token->accessToken)->get('https://api.github.com/user/repos');

lease() refreshes first when the access token expires within pipes.lease_refresh_skew_seconds (60 s). The answers, in order:

metadata carries the non-secret parts of the token response an app needs to call the API at all — Salesforce's instance_url, Slack's team.id, Notion's workspace_id.

Refresh

cbox-id:pipes:refresh runs every five minutes from the scheduler (pipes.schedule) and refreshes every active connection whose access token expires within pipes.refresh_ahead_seconds (10 min). The sweep is latency, not correctness: a lease refreshes on its own when it has to.

A refresh is single-flight. A refresh token is one-shot at every provider that rotates them, and spending it twice can revoke the whole grant. A refresh first claims the connection with one atomic UPDATE on refresh_claimed_until; whoever wins refreshes, a lease that loses waits up to pipes.refresh_wait_milliseconds and then uses what the winner stored, and the sweep that loses moves on. A claim held by a process that died lapses after pipes.refresh_claim_seconds.

When the provider refuses the refresh token (invalid_grant, Slack's invalid_refresh_token, HubSpot's BAD_REFRESH_TOKEN, GitHub's bad_refresh_token), or the token expired with nothing to refresh it with, the connection becomes needs_reauth and pipe.connection.needs_reauth is emitted. An outage (a 5xx, a 429, a timeout) or a refusal of the client (invalid_client) is transient: the connection stays active, refresh_failures and last_error record it, and the next attempt may succeed.

Disconnect

disconnect() revokes at the provider where it can (see the catalogue table), revokes both tokens in the vault, deletes the connection and emits pipe.connection.disconnected with revoked_at_provider. Revoking at the provider is best effort; forgetting the tokens here is not.

Events

Payloads name the connection, user and provider — never a token. See the webhook event reference.

Testing

Testing\InteractsWithPipes runs the real flow with only the provider faked:

uses(InteractsWithPipes::class);

$pipe = $this->configurePipe('github');
$this->grantPipe($pipe, 'cid_app');
$this->connectPipeAccount('github', 'user_1', ['access_token' => 'gho_test']);

expect($this->leasePipeToken('github', 'user_1', 'cid_app')->accessToken)->toBe('gho_test');

Where to go next

• Connect a person's third-party account — the recipe end to end.
• Security: Pipes — what protects the tokens, and the honest limits.
• AI token vault — the store every pipe token lives in.