OAuth Connect
Operations of the Connector Gateway API. Paths are relative to your deployment's API host.
GET /api/connector-gateway-api/providers/{provider}/authorize
Start the OAuth consent flow for an OAuth2 connector. Derives the org from the authenticated context, resolves the app credential (org → platform → env), opens a short-TTL single-use flow, and returns authorizeUrl: a single-use launch link on the callback host for the frontend to navigate to top-level. The launch binds the flow to that browser (a __Host- cookie) and redirects to the provider. returnPath must be /org/connections, the only page that handles an OAuth consent return; anything else is 400 RETURN_PATH_NOT_ALLOWED.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | |
connectionName | query | string | no | Name of the connection this consent is for. Send it ONLY when adding a SECOND account for a provider this organization is already connected to — it is what makes the new account its own connection instead of replacing the credential on the existing one. Omit for the ordinary connect and for re-consenting an account already held. The new connection is created NOT default, so nothing that resolves the default silently moves onto it. |
connector | query | string | yes | ConnectorKind value being connected (e.g. GMAIL). |
frontendBaseUrl | query | string | yes | Absolute frontend base URL (validated against the allowlist). |
mailbox | query | string | no | Mailbox address / user id to watch, for mail-intake connectors (Gmail / MS365). Pinned into the signed state so the post-consent callback can establish the watch/subscription and bind push routing. |
returnPath | query | string | no | Frontend page to return to after consent: exactly one of the pages that handle the return, /org/connections or /projects (no query). Defaults to /org/connections; any other value is 400 RETURN_PATH_NOT_ALLOWED. |
scopeTier | query | OAuthConnectScopeTier | no | Resolution-ladder tier the resulting connection is owned at. Defaults to 'org' — every OAuth connection made before this parameter existed is an org-tier one, so the default is what keeps an existing frontend, and a re-consent of an existing connection, landing on exactly the row they already do. 'user' owns the connection for a single person (the caller unless userId says otherwise) — this is "connect MY account, not the company one", and it is what makes the credential the person's rather than the organisation's. Those two are the ONLY admissible values on this route; anything else is a 400 from validation. |
userId | query | string | no | Owning user. Only valid when scopeTier='user' (FORBIDDEN otherwise, 400). Defaults to the authenticated caller's own subject when omitted; a value that differs from the caller requires org-admin authority (403 otherwise) — the same rule that governs creating a user-scoped connection through the connections API. It is the ONLY identity segment this route reads from the query: the org is always the authenticated context, never a query value. |
| Status | Description | Body |
|---|---|---|
| 200 | application/json OAuthAuthorizeResponseDtoDataEnvelope | |
| 400 | application/problem+json ProblemDetailsDto | |
| 401 | application/problem+json ProblemDetailsDto | |
| 403 | application/problem+json ProblemDetailsDto | |
| 404 | application/problem+json ProblemDetailsDto | |
| 409 | application/problem+json ProblemDetailsDto | |
| 422 | application/problem+json ProblemDetailsDto | |
| 500 | application/problem+json ProblemDetailsDto |
GET /api/connector-gateway-api/providers/{provider}/callback
OAuth consent callback. Verifies the signed state and that THIS browser launched the flow (the __Host- binding cookie; otherwise refused before any exchange, with connection_error=browser_binding_*), exchanges the code for tokens, proves the mailbox and PARKS the sealed result — it binds nothing. 302-redirects back to the frontend with connection_oauth_ref (an opaque reference for oauth-connect/complete) or connection_error.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | |
code | query | string | no | Authorization code returned by the provider. |
error | query | string | no | Provider-reported consent error, if any. |
state | query | string | yes | Signed state token minted at authorize time. |
| Status | Description | Body |
|---|---|---|
| 400 | application/problem+json ProblemDetailsDto | |
| 401 | application/problem+json ProblemDetailsDto | |
| 403 | application/problem+json ProblemDetailsDto | |
| 404 | application/problem+json ProblemDetailsDto | |
| 409 | application/problem+json ProblemDetailsDto | |
| 422 | application/problem+json ProblemDetailsDto | |
| 500 | application/problem+json ProblemDetailsDto |
POST /api/connector-gateway-api/providers/{provider}/oauth-connect/complete
Complete an OAuth consent: bind the tokens the callback parked under parkRef to the caller's org. Only the member who started the consent, in the org it was started for (and, at user tier, the owning user), can complete it; once, before the flow expires. Any other caller, a replay or an expired reference is 403 OAUTH_CONSENT_COMPLETION_REFUSED.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes |
Request body: application/json OAuthConsentCompleteBodyDto
| Status | Description | Body |
|---|---|---|
| 200 | application/json OAuthConsentCompleteResponseDtoDataEnvelope | |
| 400 | application/problem+json ProblemDetailsDto | |
| 401 | application/problem+json ProblemDetailsDto | |
| 403 | application/problem+json ProblemDetailsDto | |
| 404 | application/problem+json ProblemDetailsDto | |
| 409 | application/problem+json ProblemDetailsDto | |
| 422 | application/problem+json ProblemDetailsDto | |
| 500 | application/problem+json ProblemDetailsDto |