GET /v1/github/installation/install-url

Returns a one-time URL that, when opened in the browser, walks your user through installing the Layers GitHub App on the org or repos they choose. After install, GitHub redirects back to your returnUrl with installation_id and state query parameters — you then POST the installation_id to POST /v1/github/installation.

returnUrl must be on your key's allowedReturnDomains list. Calls with an unlisted URL fail with 403 RETURN_URL_NOT_ALLOWED so a compromised key can't redirect the user somewhere it shouldn't. URLs expire after 15 minutes.

Example request

curl "https://api.layers.com/v1/github/installation/install-url?returnUrl=https%3A%2F%2Fapp.gicgrowth.com%2Flayers%2Fcallback" \
  -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..."

const { authUrl, state, expiresAt } = await layers.github.installUrl({
  returnUrl: "https://app.gicgrowth.com/layers/callback",
});
// Redirect the user to authUrl.

url = layers.github.install_url(
    return_url="https://app.gicgrowth.com/layers/callback",
)
# Redirect the user to url["authUrl"].

Response

{
  "authUrl": "https://github.com/apps/layers-connector/installations/new?state=lUNN5tIRm-K3...&redirect_uri=https%3A%2F%2Fapp.gicgrowth.com%2Flayers%2Fcallback",
  "installUrl": "https://github.com/apps/layers-connector/installations/new?state=lUNN5tIRm-K3...&redirect_uri=https%3A%2F%2Fapp.gicgrowth.com%2Flayers%2Fcallback",
  "state": "lUNN5tIRm-K3a8sBXvBQDxVOCgz2x9YK",
  "expiresAt": "2026-04-18T19:29:09.000Z"
}

Errors

See also

• POST /v1/github/installation — post back the installation_id
• Return-URL allowlist — security rationale