Skip to main content
When your product acts on behalf of individual users, each one needs their own provider connection. The Engine owns that flow end to end: the app registration, the consent round trip, encrypted token storage, and refresh. Tokens are never returned to your application. There are two separate things here, easy to conflate:
  • The app registration — your client_id and client_secret with the provider. One per bucket and service.
  • A user connection — one person’s grant against that registration. Many per registration.

​
Register the OAuth app

This is an immediate admin action. No workspace.yaml field, no plan or apply — it takes effect on save.
Or answer per field:
There are no --client-id, --client-secret, or --redirect-uri flags. The whole registration is one ;-delimited value, and the key names must be exactly client_id, client_secret, and redirect_uri.
Every field is required the first time. Afterwards, omitting a field leaves it unchanged — so rotating just the redirect URI does not mean resupplying the secret. A key present but blank (client_secret=) is rejected as an attempt to erase a credential. Omitted means “leave as-is”; blank means “make it empty,” and only one of those is allowed.

​
connect set flags

​
Check what is registered

You get auth_type, auth_name, enabled, and redirect_uri in plaintext, plus has_client_id and has_client_secret as booleans — never the decrypted values. This is the only way to check registration state. bucket services shows a count, and workspace.yaml and workspace sync do not reflect it at all, because app registration was deliberately kept out of the declarative surface.

​
Connect a user

Omit --scope to request the service’s declared scope catalogue. OIDC subsets must include openid.

​
workspace service connect flags

That --user-ref is the same value your application later sends as endUserRef, or an agent sends as X-Fused-End-User-Ref. Keep it stable.

​
Refresh happens without you

Nobody refreshes a token through the CLI or the SDK. The Engine refreshes eligible connections at startup and hourly, scheduling from whichever expires first. An expired access token is not a reconnect — the Engine can rotate it while the refresh token is still good. A connection becomes reconnect_required only when refresh material is missing, expired, revoked, or rejected. Then you run the same connect flow again for that bucket, service, auth name, and user reference.
Never treat an unexpected provider 401 or 403 as permission to replay a mutation.

​
One user, several tenants

A single OAuth token can front several provider sites, shops, or accounts. The Engine discovers them and picks a default when there is exactly one.
With several resources and no default, a call must pass an explicit X-Fused-Resource-ID or resourceId, or it fails with a structured ambiguity error. rediscover drops resources the provider no longer returns; if the default disappears, selection falls back to the ordinary rules rather than routing to a stale tenant.

​
Who has connected

This lists every end user who has connected to any service through the bucket, and whether their token is healthy. Do not confuse it with workspace connection resources, which is about one already-connected user’s reachable tenants.

Share the bucket

Let other teams select this bucket without handing them its contents.