Authenticating as a GitHub App installation

You can make your GitHub App authenticate as an installation in order to make API requests that affect resources owned by the account where the app is installed.

In this article

About authentication as a GitHub App installation

Once your GitHub App is installed on an account, you can make it authenticate as an app installation for API requests. This allows the app to access resources owned by that installation, as long as the app was granted the necessary repository access and permissions. API requests made by an app installation are attributed to the app. For more information about installing GitHub Apps, see Installing your own GitHub App.

For example, if you want your app to change the Status field of an issue on a project owned by an organization called "octo-org," then you would authenticate as the octo-org installation of your app. The timeline of the issue would state that your app updated the status.

To make an API request as an installation, you must first generate an installation access token. Then, you will send the installation access token in the Authorization header of your subsequent API requests. You can also use GitHub's Octokit SDKs, which can generate an installation access token for you.

Some REST API endpoints do not accept installation access tokens, and most REST API endpoints require your app to have certain permissions to use an endpoint. To see whether a REST API endpoint accepts installation access tokens and to see what permissions are required, refer to the documentation for the endpoint.

App installations can also use the GraphQL API. Similar to the REST API, the app must have certain permissions to access objects in the GraphQL API. For GraphQL requests, you should test that your app has the required permissions for the GraphQL queries and mutations that you want to make.

You can also use an installation access token to authenticate for HTTP-based Git access. Your app must have the "Contents" repository permission. You can then use the installation access token as the HTTP password. Replace TOKEN with the installation access token: git clone https://x-access-token:TOKEN@github.com/owner/repo.git.

Requests made with an installation access token are sometimes called "server-to-server" requests.

For more information about authenticating as an app on behalf of a user instead of as an app installation, see Authenticating with a GitHub App on behalf of a user.

Using an installation access token to authenticate as an app installation

To authenticate as an installation with an installation access token, first use the REST API to generate an installation access token. Then, use that installation access token in the Authorization header of a REST API or GraphQL API request. The installation access token will expire after 1 hour.

Generating an installation access token

  1. Generate a JSON web token (JWT) for your app. For more information, see Generating a JSON Web Token (JWT) for a GitHub App.

  2. Get the ID of the installation that you want to authenticate as.

    If you are responding to a webhook event, the webhook payload will include the installation ID.

    You can also use the REST API to find the ID for an installation of your app. For example, you can get an installation ID with the GET /users/{username}/installation, GET /repos/{owner}/{repo}/installation, GET /orgs/{org}/installation, or GET /app/installations endpoints. For more information, see REST API endpoints for GitHub Apps.

    You can also find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about navigating to the settings page for your GitHub App, see Modifying a GitHub App registration.