Start Source Oauth

Begin the platform OAuth install flow: return the provider authorize URL for the client to open.

The state minted here is bound to the calling tenant and user. The response carries the authorize_url (open it in a popup) and the state: poll /oauth/grant with the state to collect the outcome, which keeps working when a provider's Cross-Origin-Opener-Policy severs the popup's opener (the callback postMessage is only a best-effort fast path).

The optional environment in the body picks WHICH of the connector's authorization environments to use — for Salesforce, production (the default) or sandbox, whose orgs cannot authenticate at the production login host at all. The schema contract's oauth.environments lists the valid keys. It is a key into that fixed set, never a host: an unknown one is a 400.

404 for a connector that declares no OAuth descriptor (capabilities.oauth_connect is false); 400 for an unknown environment, or if the platform app/base URL is not provisioned for this environment. No secret is issued to the browser. A 400 that concerns one form field (a per-account host the start refused, such as a Zendesk subdomain with no live account) also carries fields: [{"field", "message"}] beside the string detail, the shape a refused create uses.

A connector whose flow runs as the customer's own OAuth client (the contract's oauth.client_fields) takes that client's client_id and client_secret in the body; on edit, omit the secret (or send the mask) with source_id to keep the source's stored secret.