Start a connect request
const url = 'https://example.com/v1/connections/requests/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/start';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"installationId":"example","newInstallation":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/connections/requests/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/start \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "installationId": "example", "newInstallation": true }'Makes a fresh sign-in state, good for 10 minutes, and returns the app’s consent page to send the person to. Records who started it: only they may finish it. A repeat starts again and never gets the first answer back: with an Idempotency-Key, a retry gets 409 idempotency-key-replay-withheld. A GitHub App’s goes to the app’s install page while the app has no installation, or with newInstallation; otherwise to GitHub’s authorization, and the finish attaches the installation picked with installationId, one of the request’s installations.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The connect request id (a UUID).
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).
Request Body
Section titled “Request Body”Optional, and a GitHub App’s only: the installation to attach, or a new one. Leave it out for any other app.
object
The installation to attach: one of the request’s installations.
true: go to the app’s install page to install it on another account, even when it has installations. Not with installationId.
Examplegenerated
{ "installationId": "example", "newInstallation": true}Responses
Section titled “Responses”Where to send the person.
object
The app’s consent page, with a fresh sign-in state good for 10 minutes. Send the person there.
Examplegenerated
{ "authorizeUrl": "https://example.com"}requestId is not a UUID; a malformed body or unknown field; both installationId and newInstallation; or either on a request whose app is not a GitHub App (bad-input, details.field).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No request with that id, or not the caller’s (connection-request-not-found).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Idempotency-Key was reused with a different body, or a retry of one that succeeded (idempotency-key-replay-withheld); or the request was finished already (connection-request-used).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request expired (connection-request-expired).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}