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
- The agent sends a normal API request through the gateway.
- If more than one granted account could serve it, the gateway answers
409with the list of choices instead of guessing. - The agent retries the identical request with the
x-onecli-connection-idheader naming one choice. - The gateway injects that account’s credentials and forwards.
The 409 responses
Two variants, same retry contract. Same app, several accounts: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
Stale ids: the 404
If the header names a connection that no longer exists (deleted, or the grant was revoked), the gateway answers404 with the current choices — note there is no example field on this one:
connections and retry.
Discovering accounts up front
Successfully forwarded responses advertise the accounts that could serve that request in thex-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.
Related
- Gateway errors — every error body the gateway returns on proxied traffic
- Agent access — granting accounts to agents