Authenticating as a GitHub App

About authentication as a GitHub App

You must authenticate as a GitHub App in order to make REST API requests as the application. For example, if you want to use the API to generate an installation access token for accessing organization resources, list installations across organizations for your app, or suspend an app installation, you must authenticate as an app.

If a REST API endpoint requires you to authenticate as an app, the documentation for that endpoint will indicate that you must use a JWT to access the endpoint. The GraphQL API does not support any queries or mutations that require you to authenticate as an app.

Using a JSON Web Token (JWT) to authenticate as a GitHub App

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. Include the JWT in the Authorization header of your request. In the following example, replace YOUR_JWT with your JWT.

   curl --request GET \
   --url "http(s)://HOSTNAME/api/v3/app/installations" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer YOUR_JWT"

Using the Octokit.js SDK to authenticate as a GitHub App

You can use GitHub's Octokit.js SDK to authenticate as a GitHub App. One advantage of using the SDK to authenticate is that you do not need to generate a JSON web token (JWT) yourself. Additionally, the SDK will take care of regenerating the JWT when it expires.

1. Get the ID of your app. You can find your app's ID on the settings page for your GitHub App. For more information about navigating to the settings page for your GitHub App, see "Modifying a GitHub App registration."

2. Generate a private key. For more information, see "Managing private keys for GitHub Apps."

3. Import App from octokit.

   JavaScript

   import { App } from "octokit";
   

4. Create a new instance of App. In the following example, replace APP_ID with a reference to your app's ID. Replace PRIVATE_KEY with a reference to the value of your app's private key.

   JavaScript

    const app = new App({
     appId: APP_ID,
     privateKey: PRIVATE_KEY,
   });
   

5. Use an octokit method to make a request to a REST API endpoint that requires a JWT. For example:

   JavaScript

   await app.octokit.request("/app")