1.4.2.1 Web Application Flow

The web application flow to authorize users for your app is:

1. Users are redirected to request their GitHub identity

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

   • Parameters

     ‘client_id’

     (string) Required The client ID you received from GitHub when you registered.

     ‘redirect_url’

     (string) Optional The URL in your application where users will be sent after authorization.

     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
     

     Localhost redirect urls

     • The optional ‘redirect_uri’ parameter can also be used for localhost URLs
     • If the application specifies a localhost URL and a port, then after authorizing the application users will be redirected to the provided URL and port.
     • The ‘redirect_uri’ does not need to match the port specified in the callback url for the app.
     • For the http://localhost/path callback URL, you can use this ‘redirect_uri’:

       http://localhost:1234/path
       

     ‘login’

     (string) Suggests a specific account to use for signing in and authorizing the app.

     ‘scope’

     (string) A space-delimited list of scopes.

     ‘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 when 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. The temporary code will expire after 10 minutes. If the states don’t match, then a third party created the request, and you should abort the process.

   Exchange this code for an access token:

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

   • Parameters

     ‘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) Required 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. Your app accesses the API with the user’s access token

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

Authorization: token OAUTH-TOKEN
GET https://api.github.com/user

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

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