---
title: "Install GitHub App"
method: POST
path: "/v2/github.installApp"
tags: ["github"]
---

# Install GitHub App

`POST /v2/github.installApp`

Start installing the Unkey GitHub App for your workspace. Returns a GitHub
App install URL: open it in a browser to install the app and grant
repository access. After installation GitHub returns to Unkey, which binds
the installation to your workspace and lands you in the workspace settings.

Installation is workspace-wide and takes no parameters. Once installed, link
repositories to individual apps with the `git` field on `apps.createApp` and
`apps.updateApp`.

**Required Permissions**

Your root key must have the following permission:
- `workspace.*.install_github`

## Response `200`

Install URL created. Open the returned url to install the GitHub App and
finish binding it to your workspace.

- V2GithubInstallAppResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2GithubInstallAppResponseData, required
    - `url` string, uri, required — The GitHub App install URL. Open it in a browser to install the app and grant repository access. After installation GitHub returns to Unkey, which binds the installation and lands you in the workspace settings.
    - `expiresAt` integer, required — Unix timestamp in milliseconds after which the URL's signed state expires and the link must be requested again.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `workspace.*.install_github`)
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)