The API supports Basic Authentication as defined in
RFC2617 with a few slight differences.
The main difference is that the RFC requires unauthenticated requests to be
answered with 401 Unauthorized responses. In many places, this would disclose
the existence of user data. Instead, the GitHub API responds with 404 Not Found.
This may cause problems for HTTP libraries that assume a 401 Unauthorized
response. The solution is to manually craft the Authorization header.
We recommend you use OAuth tokens to authenticate to the GitHub API. OAuth tokens include personal access tokens and enable the user to revoke access at any time.
curl -u username:token https://api.github.com/user
This approach is useful if your tools only support Basic Authentication but you want to take advantage of OAuth access token security features.
Deprecation Notice: GitHub will discontinue password authentication to the API. You must now authenticate to the GitHub API with an API token, such as an OAuth access token, GitHub App installation access token, or personal access token, depending on what you need to do with the token. Password authentication to the API will be removed on November 13, 2020. For more information, including scheduled brownouts, see the blog post.
To use Basic Authentication with the GitHub API, simply send the username and password associated with the account.
For example, if you're accessing the API via cURL, the following command
would authenticate you if you replace <username> with your GitHub username.
(cURL will prompt you to enter the password.)
curl -u username https://api.github.com/user
If you have two-factor authentication enabled, make sure you understand how to work with two-factor authentication.
Note: Integrations and OAuth applications that generate tokens on behalf of others are automatically whitelisted.
If you're using the API to access an organization that enforces SAML SSO for authentication, you'll need to create a personal access token (PAT) and whitelist the token for that organization. Visit the URL specified in X-GitHub-SSO to whitelist the token for the organization.
curl -v -H "Authorization: token TOKEN" https://api.github.com/repos/octodocs-test/test X-GitHub-SSO: required; url=https://github.com/orgs/octodocs-test/sso?authorization_request=AZSCKtL4U8yX1H3sCQIVnVgmjmon5fWxks5YrqhJgah0b2tlbl9pZM4EuMz4 { "message": "Resource protected by organization SAML enforcement. You must grant your personal token access to this organization.", "documentation_url": "https://help.github.com" }
When requesting data that could come from multiple organizations (for example, requesting a list of issues created by the user), the X-GitHub-SSO header indicates which organizations require whitelisting:
curl -v -H "Authorization: token TOKEN" https://api.github.com/user/issues X-GitHub-SSO: partial-results; organizations=21955855,20582480
The value organizations is a comma-separated list of organization IDs for organizations that require whitelisting.