Skip to content
Kindgi

Rename a connection, or make it your main

View as Markdown
PATCH
/v1/connections/{connectionId}
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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
connectionId
required
string format: uuid

The connection id (a UUID).

Header Parameters

Section titled “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

Section titled “Request Bodyrequired”
Media typeapplication/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
{
  "main": true,
  "label": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The connection, renamed or made main.

Media typeapplication/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
{
  "owner": {
    "kind": "member"
  },
  "state": "working",
  "removedReason": "disconnected",
  "withdrawn": "at-app"
}

400

Section titled “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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No connection with that id, it was disconnected, or it’s not the caller’s (connection-not-found).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “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).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

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

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “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).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also