About authentication
Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a personal access token, generate a token with a GitHub App, or use the built-in GITHUB_TOKEN
in a GitHub Actions workflow.
After creating a token, you can authenticate your request by sending the token in the Authorization
header of your request. For example, in the folllowing request, replace YOUR-TOKEN
with a reference to your token:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"
Note: In most cases, you can use Authorization: Bearer
or Authorization: token
to pass a token. However, if you are passing a JSON web token (JWT), you must use Authorization: Bearer
.
Failed login limit
If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a 404 Not Found
or 403 Forbidden
response. Authenticating with invalid credentials will initially return a 401 Unauthorized
response.
After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with a 403 Forbidden
response. For more information, see "Rate limits for the REST API."
Authenticating with a personal access token
If you want to use the GitHub REST API for personal use, you can create a personal access token. For more information about creating a personal access token, see "Managing your personal access tokens."
Your personal access token requires specific scopes in order to access each REST API endpoint. For general guidance about what scopes to choose, see "Scopes for OAuth apps."
Authenticating with a token generated by an app
If you want to use the API for an organization or on behalf of another user, GitHub recommends that you use a GitHub App. For more information, see "About authentication with a GitHub App."
Your GitHub App requires specific permissions in order to access each REST API endpoint. For more information about the permissions that are required for each endpoint, see "Permissions required for GitHub Apps."
You can also create an OAuth token with an OAuth app to access the REST API. However, GitHub recommends that you use a GitHub App instead. GitHub Apps allow more control over the access and permission that the app has.
Using basic authentication
Some REST API endpoints for GitHub Apps and OAuth apps require you to use basic authentication to access the endpoint. You will use the app's client ID as the username and the app's client secret as the password.
For example:
curl --request POST \
--url "http(s)://HOSTNAME/api/v3/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"
--data '{
"access_token": "ACCESS_TOKEN_TO_CHECK"
}'
The client ID and client secret are associated with the app, not with the owner of the app or a user who authorized the app. They are used to perform operations on behalf of the app, such as creating access tokens.
If you are the owner of a GitHub App or OAuth app, or if you are an app manager for a GitHub App, you can find the client ID and generate a client secret on the settings page for your app. To navigate to your app's settings page:
- In the upper-right corner of any page on GitHub, click your profile photo.
- Navigate to your account settings.
- For an app owned by a personal account, click Settings.
- For an app owned by an organization:
- Click Your organizations.
- To the right of the organization, click Settings.
- In the left sidebar, click Developer settings.
- In the left sidebar, click GitHub Apps or OAuth apps.
- For GitHub Apps, to the right of the GitHub App you want to access, click Edit. For OAuth apps, click the app that you want to access.
- Next to Client ID, you will see the client ID for your app.
- Next to Client secrets, click Generate a new client secret to generate a client secret for your app.
Authenticating in a GitHub Actions workflow
If you want to use the API in a GitHub Actions workflow, GitHub recommends that you authenticate with the built-in GITHUB_TOKEN
instead of creating a token. You can grant permissions to the GITHUB_TOKEN
with the permissions
key. For more information, see "Automatic token authentication."
If this is not possible, you can store your token as a secret and use the name of your secret in your GitHub Actions workflow. For more information about secrets, see "Using secrets in GitHub Actions."
Authenticating in a GitHub Actions workflow using GitHub CLI
To make an authenticated request to the API in a GitHub Actions workflow using GitHub CLI, you can store the value of GITHUB_TOKEN
as an environment variable, and use the run
keyword to execute the GitHub CLI api
subcommand. For more information about the run
keyword, see "Workflow syntax for GitHub Actions."
In the following example workflow, replace PATH
with the path of the endpoint. For more information about the path, see "Getting started with the REST API." Replace HOSTNAME
with the name of your GitHub Enterprise Server instance.
jobs:
use_api:
runs-on: ubuntu-latest
permissions: {}
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh api /PATH
Authenticating in a GitHub Actions workflow using curl
To make an authenticated request to the API in a GitHub Actions workflow using curl
, you can store the value of GITHUB_TOKEN
as an environment variable, and use the run
keyword to execute a curl
request to the API. For more information about the run
keyword, see "Workflow syntax for GitHub Actions."
In the following example workflow, replace PATH
with the path of the endpoint. For more information about the path, see "Getting started with the REST API." Replace HOSTNAME
with the name of your GitHub Enterprise Server instance.
jobs: use_api: runs-on: ubuntu-latest permissions: {} steps: - env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | curl --request GET \ --url "http(s)://HOSTNAME/api/v3/PATH" \ --header "Authorization: Bearer $GH_TOKEN"
jobs:
use_api:
runs-on: ubuntu-latest
permissions: {}
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/PATH" \
--header "Authorization: Bearer $GH_TOKEN"
Authenticating in a GitHub Actions workflow using JavaScript
For an example of how to authenticate in a GitHub Actions workflow using JavaScript, see "Scripting with the REST API and JavaScript."
Authenticating with username and password
GitHub recommends that you use a token to authenticate to the REST API instead of your password. You have more control over what a token can do, and you can revoke a token at anytime. However, you can also authenticate to the REST API using your username and password for basic authentication. To do so, you will pass your username and password with the --user
option:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \
--user USERNAME:PASSWORD