OAuth

Receives the redirect from the provider after the user grants consent. Reads the signed state cookie set by /api/oauth/start/:presetKey, verifies it, exchanges the authorization code for tokens at the provider's token endpoint, captures the granted scopes and account identity, encrypts the tokens, and upserts the Connection row for the Project Environment selected by the signed state.

After authentication, OAuth flow outcomes use a 302 redirect to the signed state's returnTo URL, or the Studio root if state is invalid. Authentication failures return 401; unexpected server failures remain 5xx.

Use a browser session or Bearer API key with current permission to connect the Project Environment pinned in the signed state. Permission is checked again before exchanging the code. API clients must return the retained state cookie and provider state value and handle the redirect manually.

Generates a PKCE pair and signed state cookie, then redirects the browser to the provider's authorization endpoint. The companion /api/oauth/callback/:presetKey endpoint completes the exchange.

Use a browser session or Bearer API key with the required Project operation permission. The Project and Environment must exist in the caller's organization, and the organization must have a verified Integration registered for the preset. OAuth state pins the selected Integration Version until the callback completes. API clients must handle the redirect manually and retain the state cookie for the callback; never forward the Perstack API key to the provider.