# Rename a connection, or make it your main

PATCH

/v1/connections/{connectionId}

```sh
curl --request PATCH \
  --url https://example.com/v1/connections/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "main": true, "label": "example" }'
```

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.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.5.0/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).

## Request Bodyrequired

application/json

One change: `label` renames it, `main: true` makes it your main.

object

\>= 1 properties <= 1 properties

**main**

`true`: your main connection of its app through its registration and env, in place of the one that was. Only the person whose connection it is makes it their main, and the company’s has none. `false` is refused: a main moves only by making another connection main. A mail trigger’s stored connection doesn’t move.

boolean

**label**

The connection’s new name, trimmed, with no control, format or invisible characters (such as bidi overrides, zero-width characters or line separators); another live connection of the same app, owner and env can’t have it, ignoring case, an emoji’s variation selector and how accented letters are encoded.

string

\>= 1 characters <= 100 characters

##### Examplegenerated

```json
{
  "main": true,
  "label": "example"
}
```

## Responses

### 200

The connection, renamed or made main.

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

##### Example

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

### 400

`connectionId` is not a UUID, or a malformed body, unknown field, both `label` and `main`, or a `label` that isn’t 1 to 100 characters with no control, format or invisible characters (such as bidi overrides, zero-width characters or line separators) (`bad-input`, `details.field`). With `main` (`details.field` `main`): `false`, since a main moves only by making another connection main; the company’s connection, which has no main; or a caller who isn’t its owner, a tenant admin too.

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, it was disconnected, or it’s 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 another live connection of the same app, owner and env has that `label`, ignoring case, an emoji’s variation selector and how accented letters are encoded (`connection-label-taken`, `details.field` `label`).

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"
  }
}
```

### 413

The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much).

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 rename 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/v0.5.0/reference/api/operations/connectionsget.md)
- [`DELETE /v1/connections/{connectionId}`: Disconnect](https://docs.kindgi.com/v0.5.0/reference/api/operations/connectionsdisconnect.md)
- [`GET /v1/connections/{connectionId}/choices`: List a connection's choices](https://docs.kindgi.com/v0.5.0/reference/api/operations/connectionschoices.md)
- [Choose a connection](https://docs.kindgi.com/v0.5.0/guides/connections/choose-a-connection.md)
- [How connections work](https://docs.kindgi.com/v0.5.0/guides/connections/reference.md)
- [Kindgi 0.5.0](https://docs.kindgi.com/v0.5.0/releases/0.5.0.md)
- [Error code `bad-input`](https://docs.kindgi.com/v0.5.0/reference/errors.md#bad-input)
- [Error code `connection-label-taken`](https://docs.kindgi.com/v0.5.0/reference/errors.md#connection-label-taken)
- [Error code `connection-not-found`](https://docs.kindgi.com/v0.5.0/reference/errors.md#connection-not-found)
- [Error code `connection-store-failed`](https://docs.kindgi.com/v0.5.0/reference/errors.md#connection-store-failed)
- [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/v0.5.0/reference/errors.md#idempotency-store-unavailable)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.5.0/reference/errors.md#request-too-large)
- [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)