List the caller's GitHub App installations

GET/api/github/app/installations

listGithubAppInstallations

Every App installation this account may use, newest first: the ones this account consented to, and the organisation installations whose org claim created a workspace where the caller is an Admin or Owner. The first half is keyed on the consenting account, so an installation whose consenting account was deleted drops out of every list while staying observable to the webhook path; the second is decided per installation by the policy layer, so a workspace Member sees none of the workspace's installations. The list and the bind ask the same policy question of the account; a token's scope and resource lock are then applied per route on top. This route needs `user:read` and no resource lock; the bind needs `repo:write` on the repository, plus the workspace action for an organisation installation. So a token can list an installation it cannot bind, or bind one it cannot list — the list is not a promise about what a bind with the same token would accept. 404 when this deployment has no GitHub App configured.

Requires authentication using a bearer token or a session cookie — see tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/github/app/installations' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN'

fetch

fetch("https://neosource.dev/api/github/app/installations", {
  method: "GET",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
  },
});

Responses

200The caller's installations

application/json

GithubAppInstallationListResponse

object

Every installation the caller's account consented to, newest first.

installationsrequired

array

items

GithubAppInstallationSummary

object

One App installation this account consented to.

account_loginrequired: string
The GitHub user or organization the App is installed on.
account_typerequired: GithubInstallationAccountType
app_installation_idrequired: GithubInstallationId
created_atrequired: integerint64
Epoch milliseconds.
last_seen_at: integer | nullint64
Epoch milliseconds of the last time GitHub told us anything about this installation. `null` until the first observation after the callback.
repository_selectionrequired: GithubRepositorySelection
staterequired: GithubInstallationState

403Forbidden — one of: forbidden, needs_scope

application/json

one of

ErrorForbidden
NeedsScopeError
object
`403` body returned when a classic OAuth token is asked for something its granted scopes do not cover — an explicit private listing without `repo`, or the one-click GitHub mirror without `admin:public_key`. `scope` names the missing grant so the client can say exactly what the token lacks. There is no elevation route to widen it any more (a re-link goes through the GitHub App, whose tokens carry no scopes), so the client's answer is to say so, never to start a handshake.
errorrequired
string
Always `needs_scope` — this body exists to carry the extra fields that kind needs.
"needs_scope"
scoperequired
string
The provider scope to request via elevation (e.g. `"repo"`).

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
404Not Found — one of: not_found
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

`GithubInstallationAccountType`

string

Whether an installation sits on a GitHub user or an organization.

"user""organization"

`GithubInstallationId`

integerint64

GitHub's App installation id (`installation.id` on every App webhook). Nothing is rejected at the type level; the `> 0` invariant is a database CHECK, because the only values that reach here come from GitHub.

`GithubRepositorySelection`

string

Whether the installation covers every repository on the account or an explicitly selected subset (`installation.repository_selection`).

"all""selected"

`GithubInstallationState`

string

Lifecycle of an App installation (`github_app_installations.state`). `Deleted` is a tombstone, not a row removal: an uninstall must stay observable so a later redelivery has something to key on.

"active""suspended""deleted"