OAuth

2 operations.

Method	Endpoint	Description
GET	`/api/oauth/callback/{presetKey}`	Complete a BYOC OAuth dance and persist the Connection
GET	`/api/oauth/start/{presetKey}`	Begin a BYOC OAuth dance for a Project Environment

Complete a BYOC OAuth dance and persist the Connection

GET /api/oauth/callback/{presetKey}

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.

Parameters

path

Name	Type	Required	Description
`presetKey`	`string`	required	Identifies the OAuth preset whose authorization flow is being requested. Applies to Complete a BYOC OAuth dance and persist the Connection.

query

Name	Type	Required	Description
`code`	`string`	optional	Carries the OAuth provider error code returned during authorization. Applies to Complete a BYOC OAuth dance and persist the Connection.
`state`	`string`	optional	OAuth CSRF and correlation token returned by the provider; send it back unchanged.
`error`	`string`	optional	Carries the OAuth provider error identifier returned during authorization. Applies to Complete a BYOC OAuth dance and persist the Connection.
`error_description`	`string`	optional	Carries the OAuth provider's human-readable error description. Applies to Complete a BYOC OAuth dance and persist the Connection.

Responses

Status	Description	Body
`302`	Redirects the browser to the Studio return URL carrying the flow outcome.	none — `none`
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

Begin a BYOC OAuth dance for a Project Environment

GET /api/oauth/start/{presetKey}

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.

Parameters

path

Name	Type	Required	Description
`presetKey`	`string`	required	Identifies the OAuth preset whose authorization flow is being requested. Applies to Begin a BYOC OAuth dance for a Project Environment.

query

Name	Type	Required	Description
`projectId`	`string`	required	Filters results to the specified Project. Applies to Begin a BYOC OAuth dance for a Project Environment.
`environmentId`	`string`	required	Selects the active Project environment coordinate. Applies to Begin a BYOC OAuth dance for a Project Environment.
`returnTo`	`string`	optional	Sets the browser return location after the OAuth flow completes. Applies to Begin a BYOC OAuth dance for a Project Environment.

Responses

Status	Description	Body
`302`	Redirects the browser to the provider's authorization URL.	none — `none`
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)