Skip to content
Kindgi

Start a connect

View as Markdown
POST
/v1/connections
curl --request POST \
  --url https://example.com/v1/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "app": "example", "appId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "projectId": "example", "permissions": [ "example" ], "for": "me", "label": "example", "reconnects": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Makes a connect request for the caller’s own account (for: 'me', the default; signed in as a person) or the company’s (for: 'company'; a tenant admin only). Send the person to the request’s connectUrl, or call POST /v1/connections/requests/{requestId}/start for the app’s consent page. The company and each person keep one connection per account, registration and environment: a connect lands on its owner’s connection of the account signed in to, which is known only at the finish, or makes a new one. To connect a given connection again, name it in reconnects; the same account is required at the finish. A run that needs a connection it lacks makes its own request and waits for it (waitingFor.connections on the run).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace 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). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
app
required

The app’s entry id.

string
/^[a-z][a-z0-9-]{1,31}$/
appId

Which registration, when the workspace has more than one for the app.

string format: uuid
projectId

When given, the registration must allow this project.

string
>= 1 characters
permissions
required

The entry’s permission keys to ask for.

Array<string>
>= 1 items <= 64 items
for

me: the caller’s own account (signed in as a person). company: the company’s account; a tenant admin only.

string
default: me
Allowed values: me company
label

The connection’s name, trimmed, with no control, format or invisible characters (such as bidi overrides, zero-width characters or line separators); another live connection of the same app, owner and env can’t have it, ignoring case, an emoji’s variation selector and how accented letters are encoded. Absent: the account’s label. A reconnect keeps the connection’s name, and doesn’t check this one against the others.

string
>= 1 characters <= 100 characters
reconnects

The connection to connect again: a live one of this connect’s own owner (the caller’s for for: 'me', the company’s for for: 'company'), on the same registration and environment. Any other id is 404 connection-not-found, the same answer as for one that doesn’t exist. The same account is required at the finish, and the connection keeps its name. Absent: a person’s connect, like the company’s, asks only for the permissions it lists; at the finish it lands on the owner’s connection of the account signed in to, when there is one (when it’s connected, reconnected is true; a grant short of what that connection holds leaves it as it was, and the connect is declined with missing unless the connection is working and already holds what was asked), else makes a new one.

string format: uuid

Responses

Section titled “Responses”

201

Section titled “201”

Connect request made.

Media typeapplication/json

A connect: the owner goes to connectUrl, consents at the app, and comes back. A run that needs a connection it lacks waits on one.

object
requestId
required
string format: uuid
envName
required
string
appId
required
string format: uuid
app
required

The app’s entry id.

string
owner
required

Who owns a connection: one member (kind: member, with their userId), or the company (kind: company, the workspace’s own account).

object
kind
required
string
Allowed values: member company
userId

The member. Present when kind is member.

string
permissions
required

The permissions asked for: the ones needed, and the ones already granted.

Array<string>
says
required

What each asks for, in plain words.

Array<string>
reconnects

The connection it connects again; the same account is required.

string format: uuid
label

The name asked for the connection it makes. A reconnect keeps the connection’s.

string
runId

The run that waits for it.

string
name

The tool’s name for the connection, when a run waits.

string
startedBy

Who started it last: <kind>:<id>. Only they may finish it.

string
state
required
string
Allowed values: pending connected declined expired failed
failure

Why it failed: account-mismatch, app-refused, store-write-failed.

string
missing

The permissions the app granted less than asked.

Array<string>
installations

A GitHub App’s, while it’s pending: the app’s installations the person’s GitHub account reaches, when the finish found several and none was picked. They pick one and start again with installationId, or install the app on another account with newInstallation.

Array<object>

A GitHub App installation the person can reach.

object
installationId
required
string
account
required

The account it’s on: its login, or the enterprise’s slug.

object
id
required

The account’s stable id at the app.

string
label
required

What people see: an email address, a login.

string
connectionId

The connection it made.

string format: uuid
connectUrl
required

Where the owner starts.

string format: uri
expiresAt
required
string format: date-time
createdAt
required
string format: date-time
createdBy
required
string
Example
{
  "owner": {
    "kind": "member"
  },
  "state": "pending"
}

400

Section titled “400”

Malformed body, unknown field, a reconnects that isn’t a UUID or a label that isn’t 1 to 100 characters with no control, format or invisible characters (such as bidi overrides, zero-width characters or line separators) (bad-input, details.field); for: 'me' from a credential that is not a person (bad-input); or no registration that fits (connection-app-invalid, connection-app-unknown-entry).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

for: 'company' from a caller who is not a tenant admin (permission-denied).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No registration with that appId (connection-app-not-found); or reconnects names no live connection of the connect’s own owner on that registration and environment, whether another owner’s, another registration’s or environment’s, removed or unknown (connection-not-found, details.field reconnects).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Idempotency-Key was reused with a different body; another live connection of the same app, owner and env has that label, ignoring case, an emoji’s variation selector and how accented letters are encoded, and the connect isn’t a reconnect (connection-label-taken, details.field label); or the connection is still being disconnected: disconnect it again to finish, then connect (connection-removing).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also