Skip to content
Kindgi

Fetch a connection

View as Markdown
GET
/v1/connections/{connectionId}
curl --request GET \
  --url https://example.com/v1/connections/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

The connection id (a UUID).

Responses

Section titled “Responses”

200

Section titled “200”

The connection.

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 tenant’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
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 (bad-input).

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, or 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"
  }
}

See also