Disconnect

DELETE

/v1/connections/{connectionId}

curl --request DELETE \
  --url https://example.com/v1/connections/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Withdraws access at the app where it can, destroys the token and removes the connection (withdrawn says what the app did). Its owner or a tenant admin. Repeating it on a connection still removing carries on from the withdrawal.

Authorizations

• bearerAuth

Parameters

Path Parameters

connectionId

required

string format: uuid

The connection id (a UUID).

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).

Responses

200

The connection, removed.

Media typeapplication/json

One owner’s account at an app, through a registration, in one env. Never its token.

object

connectionId

required

string format: uuid

envName

required

string

appId

required

The registration it goes through.

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

account

required

Whose account a connection is at the app.

object

id

required

The account’s stable id at the app.

string

label

required

What people see: an email address, a login.

string

label

The name people know it by: the one asked for at the connect, else the account’s label. Absent on a connection made before connections had names; show account.label then.

string

main

Only ever true: the person’s main connection through its registration in its env, the one their agents use when no choice names another. A person’s first connection has none; their second connection makes the first their main. The company’s has none.

boolean

permissions

required

The entry’s permission keys the app granted.

Array<string>

state

required

working: runs can use it. needs-reconnecting: the app no longer accepts it; connect again. removing: a disconnect is under way. removed: gone.

string

Allowed values: working needs-reconnecting removing removed

stateReason

Why it’s in its state: invalid-grant (the app withdrew the grant), no-refresh-token (the app gave no way to renew it), token-missing (its stored token is gone), store-write-failed (its token couldn’t be stored at the connect), installation-missing (the GitHub App was uninstalled from the account), installation-permissions (an owner took permissions from the installation), suspended (the installation was suspended), sessions-revoked (Google revoked the person’s sessions), access-expired (the app gave no refresh token, and its access token ends within a minute, or has ended). Other values may be added; state says what to do.

string

installationId

A GitHub App’s installation.

string

accessEndsAt

When its access token ends, for a connection the app gave no refresh token. From one minute before then, it needs reconnecting (access-expired), and reads say so too. Absent for one that renews.

string format: date-time

connectedAt

required

When its current grant was stored: the connect, or the last reconnect.

string format: date-time

lastUsedAt

When a run last used it, to the hour.

string format: date-time

createdAt

required

string format: date-time

createdBy

required

string

updatedAt

required

string format: date-time

removedAt

string format: date-time

removedBy

string

removedReason

string

Allowed values: disconnected revoked-at-app uninstalled registration-removed replaced

withdrawn

What a removal did at the app. at-app: access was withdrawn there. app-failed: the app refused the revoke; the token is gone here all the same. kept-for-other-connection: another live connection uses the same grant. not-supported: the app has no revoke that would touch only this connection.

string

Allowed values: at-app app-failed kept-for-other-connection not-supported

Example

{
  "owner": {
    "kind": "member"
  },
  "state": "working",
  "removedReason": "disconnected",
  "withdrawn": "at-app"
}

400

connectionId is not a UUID (bad-input).

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

Example^generated

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

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

Example^generated

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

404

No connection with that id, or not the caller’s (connection-not-found).

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

Example^generated

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

409

Idempotency-Key was reused with a different body, or resource-state conflict.

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

Example^generated

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

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

Example^generated

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

503

The removal couldn’t be stored just now (connection-store-failed), or the Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable, with Retry-After).

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

Example^generated

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

See also

• GET /v1/connections/{connectionId}: Fetch a connection
• PATCH /v1/connections/{connectionId}: Rename a connection, or make it your main
• GET /v1/connections/{connectionId}/choices: List a connection's choices
• Error code bad-input
• Error code connection-not-found
• Error code connection-store-failed
• Error code idempotency-store-unavailable
• Every error code