# List connections

GET

/v1/connections

```sh
curl --request GET \
  --url 'https://example.com/v1/connections?owner=me&ownerKind=member&state=working&includeRemoved=false&limit=25' \
  --header 'Authorization: Bearer <token>'
```

A member sees their own; a tenant admin sees every one, unless `owner=me`. Removed connections are listed only with `state=removed`, or with the others under `includeRemoved=true`.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.3.1/reference/api.md#bearerauth)**

## Parameters

### Query Parameters

**projectId**

string

Only those whose registration allows this project.

**app**

string

Only this app’s (its entry id).

**owner**

string

Allowed values: me

`me`: only the caller’s own, even for a tenant admin.

**ownerKind**

string

Allowed values: member company

Only those a member owns, or only the company’s.

**state**

`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

Only those in this state.

**includeRemoved**

boolean

`true` lists removed connections too.

**limit**

integer

default: 25 >= 1 <= 100

1..100. Default 25.

**cursor**

string

Where the previous page ended: its `nextCursor`, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise `400 bad-input`, and the list starts again without it. Absent → first page.

## Responses

### 200

Page of connections.

application/json

object

**data**

required

Array\<object>

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

**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

**nextCursor**

string

**hasMore**

required

boolean

##### Example

```json
{
  "data": [
    {
      "owner": {
        "kind": "member"
      },
      "state": "working",
      "removedReason": "disconnected",
      "withdrawn": "at-app"
    }
  ]
}
```

### 400

An unknown `app`, `owner`, `ownerKind` or `state`, or an `includeRemoved` other than `true` or `false` (`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"
  }
}
```

### 503

The database was too busy to answer in time (`database-busy`); `Retry-After` (whole seconds) says when to try again.

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

- [`POST /v1/connections`: Start a connect](https://docs.kindgi.com/v0.3.1/reference/api/operations/connectionsconnect.md)
- [Error code `bad-input`](https://docs.kindgi.com/v0.3.1/reference/errors.md#bad-input)
- [Error code `database-busy`](https://docs.kindgi.com/v0.3.1/reference/errors.md#database-busy)
- [Every error code](https://docs.kindgi.com/v0.3.1/reference/errors.md)