Start an authorization

Creates a pending_auth connection and returns authorize_url — send the human there. The provider redirects back to the gateway's /connectors/callback, which completes the exchange and bounces to the console at /connectors?connected=<connection_id>.

The URL carries a signed, expiring state handle binding this workspace and connection; it is valid for authorize_expires_in seconds and cannot be reused afterwards.

409 provider_not_configured means this DEPLOYMENT has no OAuth application registered with the provider (its client id/secret environment variables are unset). The provider is supported; an operator has not connected it yet. Read providers[].configured from GET /v2/workspaces/{id}/connectors and render an unconfigured provider as unavailable rather than letting a click fail.

Requires the connectors:write scope. Accepts all three lanes: a session JWT (bounded by the caller's role on this workspace) or an il_* machine credential whose own scope set, workspace set and validity window cover it — both ceilings apply and neither can raise the other, so a credential carrying connectors:write is still refused where the role does not permit it.

A credential with no scope record resolves to LEGACY_DEFAULT, which does NOT include connectors:write — mint a key with it explicitly (POST /v2/workspaces/{id}/keys).