Start a connect

POST

/v1/connections

const url = 'https://example.com/v1/connections';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"app":"example","appId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","projectId":"example","permissions":["example"],"for":"me"}'
};

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 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "app": "example", "appId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "projectId": "example", "permissions": [ "example" ], "for": "me" }'

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. A run that needs a connection it lacks makes its own request and waits for it (waitingFor.connections on the run).

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

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). 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 Body^required

application/json

object

app

required

The app’s entry id.

string

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

appId

Which registration, when the tenant 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

Responses

201

Connect request made.

application/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 tenant’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

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

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

Malformed body or unknown field (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).

application/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

Example^generated

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

401

Missing / malformed / expired / revoked bearer token.

application/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

Example^generated

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

403

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

application/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

Example^generated

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

404

No registration with that appId (connection-app-not-found).

application/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

Example^generated

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

409

Idempotency-Key was reused with a different body; or the connection is still being disconnected: disconnect it again to finish, then connect (connection-removing).

application/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

Example^generated

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

413

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

application/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

Example^generated

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

500

Server error (unmapped domain code or framework crash).

application/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

Example^generated

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

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.

application/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

Example^generated

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

Start a connect

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

503

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated