Skip to main content

Connecting providers

Integrations no longer means "GitHub". Every provider in the integration catalog connects through one of two postures, and several providers support both:

  • OAuth — connect returns a pending connection plus an authorize URL; the console opens it in a popup, the provider redirects back through a callback, and the connection activates when the callback verifies.
  • Token paste — you paste a provider credential, and the paste is the proof: the platform verifies it against the provider's API in-line, and the connection returns active in a single request. No callback, no popup.

Token paste​

POST /v1/organizations/{orgId}/integrations/{provider}/connect
{
  "parentToken": "sbp_…",
  "displayName": "acme-supabase",
  "scope": "account"
}

scope is "account" (shared with child workspaces) or "workspace"; displayName is optional. The pasted credential is called the parent token because brokered credentials are later minted from it — it is encrypted into custody and never readable back.

For Supabase, personal access tokens must match sbp_[A-Za-z0-9_-]{20,200}; a value that doesn't is rejected with a field error that never echoes the token. A request carrying parentToken always takes the token path, even when OAuth is live for the provider.

Token-paste failures are 412 precondition_failed with a structured reason:

FailureDetails
Custody not configured for the providergate: "supabase_custody", reason: "not_configured"
Token valid but sees no provider orgreason: "no_org_visible"
Provider did not verify the tokenreason: "token_verification_failed"

Re-authorization​

If the workspace already binds the same provider account (the same Supabase organization, the same Cloudflare account), a fresh paste is a re-authorization, not a new connect:

  • Custody on the existing connection is refreshed — its brokered secrets and mint history keep their binding.
  • Any OAuth refresh-token custody on the connection is retired: the paste is the explicit choice, so the personal token becomes the mint parent from then on.
  • A suspended connection heals back to active.

Only a revoked connection falls through to a fresh create.

Health​

A background health cron re-verifies stored parent credentials against the provider. A token the provider no longer honors moves the connection to suspended with reason token_invalid; a later re-auth heals it.

note

Personal-token parents are never rotated and never revoked provider-side by the platform — they are only forgotten (custody deleted). The token remains valid at the provider until you revoke it there; Orunbase just stops holding it.

One provider account, many workspaces​

The same Cloudflare account or Supabase organization may back one connection per workspace — each workspace holds its own custody, its own mint ledger, and its own connection lifecycle. The re-auth guard above is org-scoped: another workspace's binding of the same provider account is invisible to your connect and never blocks it.

Two bindings stay globally unique across all workspaces, because inbound webhooks must route one event to exactly one tenant: