Other authentication methods

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 OAuth and personal access tokens

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.

Via username and password

Authenticating for SAML SSO

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 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: 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://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: 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 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.