Pipes
Pipes
Console page: Developers › Pipes (environment console) For your users: My account › Connected services
A pipe lets a person connect their own account at another service, so your app can call that service's API on their behalf: list their GitHub repositories, read their Google Calendar, post to Slack as them, sync their Salesforce contacts.
Cbox ID runs the OAuth flow, stores the person's tokens encrypted in the token vault, refreshes them before they expire, and gives a fresh access token to the apps you grant when they ask. Your app never stores a third-party token.
Providers: GitHub, Google, Microsoft 365, Slack, Salesforce, HubSpot, Linear, Notion.
How it fits together
- You create an OAuth app at the provider (for example a GitHub OAuth App) and enter its client ID and secret here. That is the pipe.
- You grant the apps that may use it. Nothing else can get a token through it.
- A person opens the connect page, approves access at the provider, and comes back. That is a connection, bound to that person in this environment.
- Your backend calls the lease endpoint whenever it needs to call the provider, and gets a working access token back.
End to end: list a person's GitHub repositories
1. Set up the GitHub pipe
In GitHub, open Settings › Developer settings › OAuth Apps › New OAuth App. Set the Authorization callback URL to the redirect URI shown on the Pipes page:
https://id.example.com/account/connected-services/github/callback
Generate a client secret. Then in the console open Developers › Pipes › GitHub ›
Set up, paste the client ID and secret, and set the scopes to read:user repo.
The same over the management API, with a key that holds pipes:write:
curl -X POST https://id.example.com/api/v1/pipes \
-H "Authorization: Bearer $CBOX_ID_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "github",
"client_id": "Ov23liAbCdEf",
"client_secret": "'"$GITHUB_CLIENT_SECRET"'",
"scopes": ["read:user", "repo"]
}'
The client secret is sealed when you save it and never shown again.
2. Grant your app
On the pipe's page, under Apps that may lease tokens, pick your app and select Grant. Or:
curl -X POST https://id.example.com/api/v1/pipes/$PIPE_ID/grants \
-H "Authorization: Bearer $CBOX_ID_KEY" \
-H "Content-Type: application/json" \
-d '{"client_id": "cid_01j9yk4w2g8ma1hq3zv0t5r7bc"}'
3. Send the person to connect
Link the signed-in person to the connect page. Add your app's client_id and a
return_to on one of your app's registered redirect origins, and they come back to you
afterwards:
https://id.example.com/account/connected-services/github/connect
?client_id=cid_01j9yk4w2g8ma1hq3zv0t5r7bc
&return_to=https://app.example.com/settings/integrations
They see what will be shared, in their own language, continue to GitHub, approve, and
land back on return_to with ?provider=github&status=connected (or cancelled, or
failed). A return_to that is not on your app's registered origins is ignored, and they
land on Connected services instead.
4. Lease a token and call GitHub
From your backend, with an access token for your app that carries the vault.lease
scope (client credentials is fine):
curl -X POST https://id.example.com/api/v1/vault/pipes/github/token \
-H "Authorization: Bearer $APP_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_id": "01j9yk3s7p5n4q2m1k0h8g6f4d", "purpose": "list-repos"}'
{
"access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
"token_type": "Bearer",
"provider": "github",
"user_id": "01j9yk3s7p5n4q2m1k0h8g6f4d",
"connection_id": "01j9yk5c4t3r2e1w0q9p8o7i6u",
"scopes": ["read:user", "repo"],
"expires_at": null,
"lease_expires_at": "2026-10-09T14:05:00+00:00",
"metadata": {}
}
Then call GitHub with it:
curl https://api.github.com/user/repos \
-H "Authorization: Bearer gho_16C7e42F292c6912E7710c838347Ae178B4a" \
-H "Accept: application/vnd.github+json"
In PHP:
$lease = Http::withToken($appAccessToken)
->post('https://id.example.com/api/v1/vault/pipes/github/token', [
'user_id' => $user->cbox_id,
'purpose' => 'list-repos',
]);
if (in_array($lease->status(), [404, 409], true)) {
return redirect($lease->json('connect_url')); // not connected, or must reconnect
}
$repos = Http::withToken($lease->json('access_token'))
->accept('application/vnd.github+json')
->get('https://api.github.com/user/repos')
->json();
Drop the token when you are done and lease again next time. The lease refreshes it first when it is about to expire, so you never handle a refresh token.
If your app has a token issued for the person (they signed in to your app through
Cbox ID), leave out user_id: the lease is for them, and naming anyone else is refused.
What the lease endpoint answers
| Status | error |
What to do |
|---|---|---|
| 200 | — | Use access_token. metadata has what some providers need to be called at all — Salesforce's instance_url. |
| 403 | lease_denied |
Your app is not granted this pipe, the pipe is disabled or does not exist, or (for an app owned by an organization) the person is not a member of it. The answer is the same for every reason. |
| 404 | not_connected |
The person has not connected this provider. Send them to connect_url. |
| 409 | reauthorization_required |
The provider stopped accepting the connection. Send them to connect_url to connect again. |
| 503 | temporarily_unavailable |
The provider could not refresh the token just now. Retry after Retry-After. |
Keeping tokens fresh
Tokens are refreshed in the background a few minutes before they expire, and again when your app leases one that is about to. Only one refresh runs per connection at a time, so two of your servers asking at once do not both spend the refresh token.
When the provider refuses to refresh — the person revoked your app at GitHub, or a
refresh token expired — the connection is marked needs reconnect, the
pipe.connection.needs_reauth webhook fires, and the next lease answers 409. Subscribe to
the webhook to tell the person before they hit it.
Per provider
| Provider | Good to know |
|---|---|
| GitHub | OAuth App tokens do not expire. A GitHub App with expiring user tokens is refreshed every 8 hours. |
| Refresh tokens are requested with offline access and a consent prompt, so a reconnect always yields one. | |
| Microsoft 365 | Keep offline_access in the scopes or nothing can be refreshed. Set the tenant to restrict which directories may connect. Microsoft has no revocation endpoint: disconnecting forgets the token here; the person removes consent at myapps.microsoft.com. |
| Slack | Scopes are user-token scopes. Tokens only expire and refresh when token rotation is turned on for your Slack app. metadata carries team.id. |
| Salesforce | Call the API at metadata.instance_url. Use test.salesforce.com as the login domain for sandboxes. |
| HubSpot | Tokens live 30 minutes; they are refreshed for you. |
| Linear | Scopes are comma-separated at Linear; enter them as usual here. |
| Notion | No scopes: the person picks pages on Notion's screen. The token response names no lifetime; Notion's rotating refresh token is kept, and disconnecting revokes the token at Notion. Send Notion-Version on your own API calls too. |
Disconnecting
People disconnect under My account › Connected services. You can disconnect someone
from the pipe's page (for a leaver, say), or with
DELETE /api/v1/pipes/{id}/connections/{connection_id}. Where the provider supports it,
access is revoked at the provider too.
Removing a pipe forgets every connection through it and revokes their tokens here, but does not call the provider for each person. Disconnect people first if that matters.
Things worth knowing
- The pipes pages are behind the environment step-up: a pipe holds a client secret, and a grant hands an app every connected person's token.
- Changing a pipe's scopes applies to the next connect. People already connected keep what they agreed to until they connect again.
- The audit trail records every configuration change, grant, connect, refresh, lease and disconnect, with who did it — never a token or a client secret.
- Erasing a person deletes their connections and tokens.
Related
- Token vault — the store every pipe token lives in.
- Webhooks —
pipe.connection.connected,pipe.connection.needs_reauth,pipe.connection.disconnected. - Social login — signing people in with GitHub or Google. A pipe is the other direction: your app reaching out as them.