Skip to main content
A project can connect several accounts of the same app — two Gmail inboxes, a personal and an org GitHub — and an agent can hold grants for any subset of them. That raises a question the gateway can’t answer alone: when an agent calls gmail.googleapis.com, which account should serve the request? This page documents the protocol that resolves it. The exchange happens on the agent’s ordinary proxied traffic, not on the management API.

The flow

  1. The agent sends a normal API request through the gateway.
  2. If more than one granted account could serve it, the gateway answers 409 with the list of choices instead of guessing.
  3. The agent retries the identical request with the x-onecli-connection-id header naming one choice.
  4. The gateway injects that account’s credentials and forwards.
When only one granted account matches, none of this happens — the request forwards directly.

The 409 responses

Two variants, same retry contract. Same app, several accounts:
Different apps matching the same request (for example, two integrations that both serve a shared API host):
Both carry x-should-retry: false: retrying unchanged will not succeed. The fix is adding the header — pick a connections[].id (use label and display_name to decide, or ask the user) and resend.

Retrying with a choice

The header names a connection for this request only — there is no sticky selection. Agents typically remember the id for a task and send it on every related call.

Stale ids: the 404

If the header names a connection that no longer exists (deleted, or the grant was revoked), the gateway answers 404 with the current choices — note there is no example field on this one:
Re-pick from connections and retry.

Discovering accounts up front

Successfully forwarded responses advertise the accounts that could serve that request in the x-onecli-connections response header — a JSON array of the same choice objects. An agent can read it from any successful call and start sending x-onecli-connection-id before ever hitting a 409.

Per-account permissions

Grants and policy decisions are per account. The same request can be blocked on one connection and allowed on another — for example, send_email set to allow on the support inbox but ask on the founders account. The gateway evaluates the selected account’s grant, so switching the header can change the verdict. The per-account view lives at GET /v1/policy/effective-app-permissions?provider=gmail&connectionId=conn_9f2c1b.

In the SDK

The Node SDK exports the header names and a typed parser for these bodies (parseGatewayError, CONNECTION_ID_HEADER, CONNECTIONS_HEADER), so agent-side code can implement the retry without string-matching.