Device Code Flow - OAuth 2.0 Playground

1

Step 1

Request a device code from the authorization server

2

Step 2

Instruct the user where to enter the code

3

Step 3

Poll the authorization server periodically until the code has been successfully entered

1. Request a Device Code

The first step of the Device flow is to request a device code. This is done with a simple POST request to the device code endpoint.

POST https://example.okta.com/device

client_id=https://www.oauth.com/playground/

2. Tell the User to Enter the Code

The response from the server includes the device code, a code to display to the user, and the URL the user should visit to enter the code.

{
  "device_code": "NGU5OWFiNjQ5YmQwNGY3YTdmZTEyNzQ3YzQ1YSA",
  "user_code": "BDWD-HQPK",
  "verification_uri": "https://example.okta.com/device",
  "interval": 5,
  "expires_in": 1800
}

Note: This is just an example URL, since the Okta API does not implement the Device Flow. You can use the Google API if you want to try this against a real service.

You'll need to present the verification_uri and user_code to the user and instruct them to enter the code at the URL. How you do this depends on the capabilities of the device. For example, on a smart TV, it is relatively easy to display both items and instructional text on the screen. On a device with a more limited display capability, it may be more challenging.

3. Poll the Token Endpoint

While you wait for the user to visit the URL, sign in to their account, and approve the request, you'll need to poll the token endpoint with the device code until an access token or error is returned.

POST https://example.okta.com/token

grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id=https://www.oauth.com/playground/
&device_code=NGU5OWFiNjQ5YmQwNGY3YTdmZTEyNzQ3YzQ1YSA

Before the user has finished signing in and approving the request, the authorization server will return a status indicating the authorization is still pending.

HTTP/1.1 400 Bad Request

{
  "error": "authorization_pending"
}

When the user approves the request, the token endpoint will respond with the access token.

HTTP/1.1 200 OK

{
  "token_type": "Bearer",
  "access_token": "RsT5OjbzRn430zqMLgV3Ia",
  "expires_in": 3600,
  "refresh_token": "b7a3fac6b10e13bb3a276c2aab35e97298a060e0ede5b43ed1f720a8"
}

Now the device can use this access token to make API requests on behalf of the user.

← Back to Flows

OAuth 2.0 Device Code Flow