client.connections

client.connections — the connections operations.

On AsyncKindgi every method is the same, awaited.

client.connections.list()

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

Signature

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

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

Signature

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

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

Signature

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

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

Signature

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

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

Signature

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

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

Signature

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

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

Signature

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.