# client.connections

> client.connections — the connections operations.

`client.connections` — the `connections` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.connections.list()`

```python signature
list(
    *,
    project_id: str | UUID | None = None,
    app: str | None = None,
    owner: Literal['me'] | None = None,
    owner_kind: Literal['member', 'company'] | None = None,
    state: Literal['working', 'needs-reconnecting', 'removing', 'removed'] | None = None,
    include_removed: bool | None = None,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> ConnectionPage
```

List connections. `GET /v1/connections`

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

## `client.connections.connect()`

```python signature
connect(
    body: CreateConnectRequestBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ConnectRequest
```

Start a connect. `POST /v1/connections`

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

## `client.connections.finish()`

```python signature
finish(
    body: FinishConnectBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ConnectFinish
```

Finish a connect. `POST /v1/connections/finish`

Takes what the app sent back to the callback page (`state` and `code`, with `installationId` and `setupAction` from a GitHub App; or `error`). Only whoever started the request may finish it. Exchanges the code, learns the account, compares what was granted with what was asked and stores the connection; a run that waits goes on. A person who declined, or who granted less than asked, gets `kind: 'declined'` and the request's `missing` permissions. A GitHub App's attaches an installation only if the person's GitHub account reaches it: the one GitHub sent back, the one they picked at the start, or the only one they reach. When they reach several and picked none, it answers `kind: 'pick-installation'`: the request stays `pending` with its `installations` to pick from (start it again with `installationId`, or `newInstallation`).

## `client.connections.get()`

```python signature
get(connection_id: str | UUID, /, *, timeout: float | None = None) -> Connection
```

Fetch a connection. `GET /v1/connections/{connectionId}`

A member's connection is its owner's or a tenant admin's. Anyone else gets the `404` of a connection that doesn't exist.

## `client.connections.disconnect()`

```python signature
disconnect(
    connection_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> Connection
```

Disconnect. `DELETE /v1/connections/{connectionId}`

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.