# Disconnect DELETE /v1/connections/{connectionId} ```sh curl --request DELETE \ --url https://example.com/v1/connections/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --header 'Authorization: Bearer ' ``` 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](https://docs.kindgi.com/reference/api.md#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. application/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\ **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 ```json { "owner": { "kind": "member" }, "state": "working", "removedReason": "disconnected", "withdrawn": "at-app" } ``` ### 400 `connectionId` is not a UUID (`bad-input`). 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 ##### Examplegenerated ```json { "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 ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 404 No connection with that id, or not the caller’s (`connection-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 ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 409 Idempotency-Key was reused with a different body, or resource-state conflict. 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 ##### Examplegenerated ```json { "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 ##### Examplegenerated ```json { "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`). 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 ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ## See also - [`GET /v1/connections/{connectionId}`: Fetch a connection](https://docs.kindgi.com/reference/api/operations/connectionsget.md) - [`PATCH /v1/connections/{connectionId}`: Rename a connection, or make it your main](https://docs.kindgi.com/reference/api/operations/connectionsupdate.md) - [`GET /v1/connections/{connectionId}/choices`: List a connection's choices](https://docs.kindgi.com/reference/api/operations/connectionschoices.md) - [Error code `bad-input`](https://docs.kindgi.com/reference/errors.md#bad-input) - [Error code `connection-not-found`](https://docs.kindgi.com/reference/errors.md#connection-not-found) - [Error code `connection-store-failed`](https://docs.kindgi.com/reference/errors.md#connection-store-failed) - [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/reference/errors.md#idempotency-store-unavailable) - [Every error code](https://docs.kindgi.com/reference/errors.md)