Skip to main content

Other authentication methods

You can use basic authentication for testing in a non-production environment.

While the API provides multiple methods for authentication, we strongly recommend using OAuth for production applications. The other methods provided are intended to be used for scripts or testing (i.e., cases where full OAuth would be overkill). Third party applications that rely on GitHub for authentication should not ask for or collect GitHub credentials. Instead, they should use the OAuth web flow.

Basic Authentication

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.

Via personal access tokens

We recommend you use fine-grained personal access tokens to authenticate to the GitHub API.

$ 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 personal access token security features.

Via username and password

Note: GitHub has discontinued password authentication to the API starting on November 13, 2020 for all GitHub.com accounts, including those on a GitHub Free, GitHub Pro, GitHub Team, or GitHub Enterprise Cloud plan. 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. For more information, see "Troubleshooting."

Authenticating for SAML SSO

Note: Integrations and OAuth applications that generate tokens on behalf of others are automatically authorized.

Note: 在大多数情况下,可以使用 Authorization: BearerAuthorization: token 传递令牌。 但是,如果要传递 JSON Web 令牌 (JWT),则必须使用 Authorization: Bearer

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 and authorize the token for that organization. Visit the URL specified in X-GitHub-SSO to authorize the token for the organization.

$ curl -v -H "Authorization: Bearer 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://docs.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 you to authorize your personal access token:

$ curl -v -H "Authorization: Bearer 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 require authorization of your personal access token.

Working with two-factor authentication

When you have two-factor authentication enabled, Basic Authentication for most endpoints in the REST API requires that you use a personal access token.

You can generate a new personal access token using GitHub developer settings. For more information, see "Creating a personal access token for the command line". Then you would use these tokens to authenticate using OAuth token with the GitHub API.