Begin the OAuth2 authorization-code flow for a connection

Builds and returns the provider's authorize URL for an existing OAuth2 connection. It does NOT redirect and does NOT exchange anything — you must send a human's browser to authorizeUrl. Takes NO request body.

SEQUENCE: (1) create the connection with POST /api/connections, supplying the piece's clientId/clientSecret; (2) call this with the new id; (3) open authorizeUrl in a browser. The provider redirects back to redirectUri ({PUBLIC_API_URL}/api/oauth2/callback), which this server handles itself — it exchanges the code and stores the encrypted tokens on the connection. That callback is a browser endpoint returning HTML; it is not part of this API and you never call it. (4) Poll GET /api/connections/{id}: a connection that completed the flow reports status: "active" and usually a tokenExpiresAt. Refresh tokens are renewed automatically at run time; there is no manual refresh endpoint.

The returned URL already carries response_type=code, client_id, redirect_uri, scope, access_type=offline, any piece-declared extra authorize params, and a signed state bound to this connection that EXPIRES AFTER 10 MINUTES. Do not cache it — mint a fresh URL per attempt.

WHERE THE ENDPOINTS COME FROM: for a piece that declares OAuth2 (auth.oauth2 in GET /api/pieces/{id}), the authorize/token URLs and default scopes are filled in for you. For the generic oauth2 piece, the connection's own config.authUrl/config.tokenUrl/config.scope are used. If the instance operator configured a MANAGED OAuth app for this provider, no per-connection clientId is needed and the instance's client id is used — but only ever against the piece's own declared authorize URL.

redirectUri is returned so you can register it with the provider; it must match what the provider has on file or the callback fails.

Does NOT accept Idempotency-Key.