Initiate OAuth2 Flow
Three-step interactive PKCE flow for MCPs that authenticate via OAuth2 rather than a static API key:
POST /oauth2/initiate(this endpoint) - builds the provider's authorization URL and stores the PKCE verifier/state server-side. Redirect the end user's browser to the returnedauthorization_url.GET /oauth2/callback- the identity provider redirects here after the user authorizes (or denies) access; this exchanges the code for tokens and redirects back to the frontend URL supplied in step 1.GET /oauth2/sessions/{deployment_id}/{entry_id}- poll or read this afterward to checkconnectedstatus; never exposes the tokens themselves.DELETEthe same path to disconnect and force a fresh flow.
Calling initiate again for the same deployment/entry overwrites any
prior in-flight or completed session.
Start the PKCE authorization-code flow for an MCP's OAuth2 provider.
Generates a PKCE verifier/challenge pair and an anti-CSRF state value, builds the provider's authorization URL, and persists the (encrypted) verifier and pending state keyed by (deployment_id, entry_id) so the callback can complete the exchange. Any prior session for the same deployment/entry is overwritten, which implicitly invalidates it - only one in-flight or completed OAuth session is kept per entry.
Args: body: Deployment/entry to authorize, optional scope override, and the frontend URL to redirect back to once the flow completes. request: Used to build the callback redirect_uri from the current host, so it always matches how this API is being reached. session: Database session. context: Caller's security context; the caller must own the deployment being authorized.
Returns: The provider authorization URL the frontend should redirect the user to, plus the generated state value.
Authorization
OAuth2AuthorizationCodeBearer In: header
Query Parameters
trueRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/oauth2/initiate" \ -H "Content-Type: application/json" \ -d '{ "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6", "entry_id": "31513983-613b-4481-b270-ae929f358bae", "redirect_uri": "string" }'{ "authorization_url": "string", "state": "string"}{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ]}