App Install Connect
Operations of the Connector Gateway API. Paths are relative to your deployment's API host.
GET /api/connector-gateway-api/providers/{provider}/install
Start the installation flow for an app-install connector. Derives the org from the authenticated context, resolves the app credential (org BYO → platform default), mints single-use PKCE-bound state, and returns installUrl: 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 one of the pages that handle the return (/org/connections, /projects); 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 installation is for. Send it ONLY when installing a SECOND account for a provider this organization already has an installation of — the installation is then written onto its own connection instead of being refused against the existing one. Omit for the ordinary install and for re-installing an account already held. The new connection is created NOT default. |
connector | query | string | yes | Connector key being connected (e.g. GITHUB). |
frontendBaseUrl | query | string | yes | Absolute frontend base URL (validated against the allowlist). |
returnPath | query | string | no | Frontend page to return to after installation: 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. |
| Status | Description | Body |
|---|---|---|
| 200 | application/json AppInstallLaunchResponseDtoDataEnvelope | |
| 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}/install/callback
App-installation callback. Refuses, before anything else, a browser without the flow's __Host- binding cookie (connection_error=browser_binding_*). Consumes the single-use signed state, exchanges the authorization code, verifies at the provider that the redirected user administers the installation, and PARKS the verified result — it binds nothing. 302-redirects back to the frontend with connection_install_ref (an opaque reference for install/complete) or connection_error.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes |
| 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}/install/complete
Complete an app installation: bind the provider-verified installation the callback parked under installRef to the caller's org. Only the member who started the installation, in the org it was started for, can complete it; once, before the flow expires. Any other caller, a replay or an expired reference is 403 APP_INSTALL_COMPLETION_REFUSED.
Authentication: bearer token (Authorization: Bearer <token>)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes |
Request body: application/json AppInstallCompleteBodyDto
| Status | Description | Body |
|---|---|---|
| 200 | application/json AppInstallCompleteResponseDtoDataEnvelope | |
| 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 |