Authorizing OAuth Apps

You can enable other users to authorize your OAuth App.

Note: GitHub's OAuth implementation supports the standard authorization code grant type. You should implement the web application flow described below to obtain an authorization code and then exchange it for a token. (The implicit grant type is not supported.)

For troubleshooting information, see the following articles:

Web application flow

The flow to authorize users for your app is:

  1. Users are redirected to request their GitHub identity
  2. Users are redirected back to your site by GitHub
  3. Your app accesses the API with the user's access token

1. Request a user's GitHub identity

GET https://github.com/login/oauth/authorize

When your GitHub App specifies a login parameter, it prompts users with a specific account they can use for signing in and authorizing your app.

Parameters

Name Type Description
client_id string Required. The client ID you received from GitHub when you registered.
redirect_uri string The URL in your application where users will be sent after authorization. See details below about redirect urls.
login string Suggests a specific account to use for signing in and authorizing the app.
scope string A space-delimited list of scopes. If not provided, scope defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with user scope and another token with repo scope, a third web flow that does not provide a scope will receive a token with user and repo scope.
state string An unguessable random string. It is used to protect against cross-site request forgery attacks.
allow_signup string Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is true. Use false in the case that a policy prohibits signups.

2. Users are redirected back to your site by GitHub

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request was created by a third party and the process should be aborted.

Exchange this code for an access token:

POST https://github.com/login/oauth/access_token

Parameters

Name Type Description
client_id string Required. The client ID you received from GitHub for your GitHub App.
client_secret string Required. The client secret you received from GitHub for your GitHub App.
code string Required. The code you received as a response to Step 1.
redirect_uri string The URL in your application where users are sent after authorization.
state string The unguessable random string you provided in Step 1.

Response

By default, the response takes the following form:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

You can also receive the content in different formats depending on the Accept header:

Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "scope":"repo,gist", "token_type":"bearer"}

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
</OAuth>

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

GET https://api.github.com/user?access_token=...

You can pass the token in the query params as shown above, but a cleaner approach is to include it in the Authorization header.

Authorization: token OAUTH-TOKEN

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user

Non-Web application flow

Use Basic Authentication to create an OAuth2 token using the interface. With this technique, a username and password doesn't need to be permanently stored and the user can revoke access at any time.

Note: When using the non-web application flow to create an OAuth2 token, make sure to understand how to work with two-factor authentication if you or your users have two-factor authentication enabled.

Redirect URLs

The redirect_uri parameter is optional. If left out, GitHub will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL's host and port must exactly match the callback URL. The redirect URL's path must reference a subdirectory of the callback URL.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

Creating multiple tokens for OAuth Apps

You can create multiple tokens for a user/application/scope combination to create tokens for specific use cases.

This is useful if your OAuth App supports one workflow that uses GitHub for sign-in and only requires basic user information. Another workflow may require access to a user's private repositories. Using multiple tokens, your OAuth App can perform the web flow for each use case, requesting only the scopes needed. If a user only uses your application to sign in, they are never required to grant your OAuth App access to their private repositories.

There is a limit to the number of tokens that are issued per user/application/scope combination. If your application requests enough tokens to go over one of the limits, older tokens will stop working.

Warning: Revoking all of a user's access to an application deletes any SSH keys the application generated on behalf of the user, including deploy keys.

Directing users to review their access

You can link to authorization information for an OAuth App so that users can review and revoke their application authorizations.

To build this link, you'll need your OAuth Apps client_id that you received from GitHub when you registered the application.

https://github.com/settings/connections/applications/:client_id

Tip: To learn more about the resources that your OAuth App can access for a user, see "Discovering resources for a user."