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.
You can authenticate your request by sending a token in the
Authorization header of your request. In the following example, 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
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.
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."
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."
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.
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.
curl --request POST \
--url "http(s)://HOSTNAME/api/v3/authorizations" \
You can find the client ID and generate a client secret on the settings page for your app. For more information about navigating to the settings page for your GitHub App, see "Modifying a GitHub App registration."
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."
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
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/user" \