# 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. The company and each person keep one connection per account, registration and environment: a connect lands on its owner's connection of the account signed in to, which is known only at the finish, or makes a new one. To connect a given connection again, name it in `reconnects`; the same account is required at the finish. 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 company connect that doesn't name `reconnects` lands on the company's connection of the account signed in to, when there is one, so one account never has two. `reconnected` says whether it landed on a connection that was already there, which keeps its name. A new connection whose name another connection took meanwhile is named the first free `<name> 2`, `<name> 3` and so on, and `labelTaken` gives the name it was to get. 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; the company's is a tenant admin's alone. Anyone else gets the `404` of a connection that doesn't exist.

## `client.connections.update()`

```python signature
update(
    connection_id: str | UUID,
    body: UpdateConnectionBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Connection
```

Rename a connection, or make it your main. `PATCH /v1/connections/{connectionId}`

One change. `label` renames it, the name people know it by: whoever may disconnect it, its owner or a tenant admin. `main: true` makes it its owner's main connection of its app through its registration and env, in place of the one that was, audited as `connection-main-set`: its owner alone, and only a person's. Making the main main again answers it as it is. A main never moves a mail trigger's stored connection. 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.

## `client.connections.choices()`

```python signature
choices(
    connection_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> ConnectionChoicePage
```

List a connection's choices. `GET /v1/connections/{connectionId}/choices`

The live choices that name the connection, in every project of this server's environment: as `connectionId`, or in a set. Whoever the connection reaches: its owner or a tenant admin. Anyone else gets the `404` of a connection that doesn't exist.