Device Flow (Developing GitHub Apps)

1.4.2.2 Device Flow

The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.

Device Flow
OAuth 2.0 Device Authorization Grant
Your app requests device and user verification codes and gets the authorization URL where the user will enter the user verification code.
```
POST https://github.com/login/device/code
```
Your app must request a:
- user verification code and
- verification URL that the app will use to prompt the user to authenticate in the next step.
- This request also returns a device verification code that the app must use to receive an access token and check the status of user authentication.
- Input parameters
  
  ‘client_id’
  
  (string) Required The client ID you received from GitHub for your app.
  
  ‘scope’
  
  (string) The scope that your app is requesting access to.
- Response
```
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
```
- Response parameters
  ‘device_code’
  
  (string) The device verification code is 40 characters and used to verify the device.
  
  ‘user_code’
  
  (string) The user verification code is displayed on the device so the user can enter the code in a browser. This code is 8 characters with a hyphen in the middle.
  
  ‘verification_uri’
  The verification URL where users need to enter the user_code
  https://github.com/login/device
  ‘expires_in’
  
  (integer) The number of seconds before the device_code and user_code expire. The default is 900 seconds or 15 minutes.
  
  ‘interval’
  (integer) The minimum number of seconds that must pass before you can make a new access token request
  POST https://github.com/login/oauth/access_token
  to complete the device authorization.
The app prompts the user to enter a user verification code at:
```
https://github.com/login/device
```
Your device will show the user verification code and prompt the user to enter the code.

3 The app polls for the user authentication status. Once the user has authorized the device, the app will be able to make API calls with a new access token.

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

Your app will make device authorization requests that poll the above uri until the device and user codes expire or the user has successfully authorized the app with a valid user code. The app must use the minimum polling interval retrieved in step 1 to avoid rate limit errors.

The user must enter a valid code within 15 minutes (or 900 seconds). After 15 minutes, you will need to request a new device authorization code with:

POST https://github.com/login/device/code

Once the user has authorized, the app will receive an access token that can be used to make requests to the API on behalf of a user.

Input parameters
‘client_id’

(string) Required The client ID you received from GitHub for your OAuth App.

‘device_code’
(string) Required The device verification code you received from the:
```
POST https://github.com/login/device/code
```
request.
‘grant_type’
(string) Required The grant type must be:
```
urn:ietf:params:oauth:grant-type:device_code
```

Response

{
 "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "token_type": "bearer",
  "scope": "user"
}

Rate limits
When a user submits the verification code on the browser, there is a there is a rate limit of 50 submissions in an hour per application.

If you make more than one access token request at:
```
POST https://github.com/login/oauth/access_token
```
within the required minimum timeframe between requests (‘interval’) you’ll hit the rate limit and receive a ‘slow_down’ error response, which adds 5 seconds to the last ‘interval’.

Error Codes for the Device Flow
- error codes