68 lines
3.7 KiB
Markdown
68 lines
3.7 KiB
Markdown
---
|
|
title: Authenticating as a GitHub App
|
|
intro: You can authenticate as a {% data variables.product.prodname_github_app %} in order to generate an installation access token or manage your app.
|
|
versions:
|
|
fpt: '*'
|
|
ghes: '*'
|
|
ghae: '*'
|
|
ghec: '*'
|
|
topics:
|
|
- GitHub Apps
|
|
shortTitle: Authenticate as an app
|
|
---
|
|
|
|
## About authentication as a {% data variables.product.prodname_github_app %}
|
|
|
|
You must authenticate as a {% data variables.product.prodname_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 {% data variables.product.prodname_github_app %}
|
|
|
|
1. Generate a JSON Web Token (JWT) for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app)."
|
|
1. Include the JWT in the `Authorization` header of your request. In the following example, replace `YOUR_JWT` with your JWT.
|
|
|
|
```shell
|
|
curl --request GET \
|
|
--url "{% data variables.product.api_url_pre %}/app/installations" \
|
|
--header "Accept: application/vnd.github+json" \
|
|
--header "Authorization: Bearer YOUR_JWT"{% ifversion api-date-versioning %}\
|
|
--header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}"{% endif %}
|
|
```
|
|
|
|
## Using the Octokit.js SDK to authenticate as a {% data variables.product.prodname_github_app %}
|
|
|
|
You can use {% data variables.product.company_short %}'s Octokit.js SDK to authenticate as a {% data variables.product.prodname_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.
|
|
|
|
{% note %}
|
|
|
|
**Note**: You must install and import `octokit` in order to use the Octokit.js library. The following example uses import statements in accordance with ES6. For more information about different installation and import methods, see [Usage](https://github.com/octokit/octokit.js/#usage) in the octokit/octokit repository.
|
|
|
|
{% endnote %}
|
|
|
|
1. On the settings page for your app, get the app's ID.
|
|
- For user-owned apps, the settings page is `https://github.com/settings/apps/APP-SLUG`.
|
|
- For organization-owned apps, the settings page is `https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG`.
|
|
|
|
Replace `APP-SLUG` with the slugified name of your app and `ORGANIZATION` with the slugified name of your organization. For example, `https://github.com/organizations/octo-org/settings/apps/octo-app`.
|
|
1. Generate a private key. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)."
|
|
1. Import `App` from `octokit`.
|
|
|
|
```javascript{:copy}
|
|
import { App } from "octokit";
|
|
```
|
|
1. 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{:copy}
|
|
const app = new App({
|
|
appId: APP_ID,
|
|
privateKey: PRIVATE_KEY,
|
|
});
|
|
```
|
|
|
|
1. Use an `octokit` method to make a request to a REST API endpoint that requires a JWT. For example:
|
|
|
|
```javascript{:copy}
|
|
await app.octokit.request("/app")
|
|
```
|