Generate Device Code and User Code (OAuth Device Flow)

post

/oauth2/v1/device

Request

Supported Media Types
Header Parameters
Body ()
Root Schema : schema
Type: object
Show Source
  • Unique ID of the client.
    Example: a5bf5db7f6c43b47b1eae399c68319c4
  • Type of response from the server (device_code)
    Example: device_code
  • Scope for which the Device Code and User Code is requested.
    Example: http://abccorp.com/quote
Back to Top

Response

Supported Media Types

200 Response

Device Code and User Code generated
Body ()
Root Schema : device
Type: object
Generated Device Code and User Code (OAuth Device Flow)
Show Source

400 Response

Invalid request
Body ()
Root Schema : error
Type: object
Error message that appears during Device Code and User Code generation
Show Source

401 Response

Unauthorized client
Body ()
Root Schema : error
Type: object
Error message that appears during Device Code and User Code generation
Show Source
Back to Top

Examples

There are several steps involved when using the Device Code grant type flow to request a device code and then obtain an access token so that a user can access a resource. The device flow is suitable for OAuth 2.0 clients that execute on devices that don???t have an easy data entry method, such as digital picture frames, game consoles, and streaming media players (for example, a Roku), and the client is not able to receive incoming requests from the authorization server.

Instead of interacting with a user???s streaming media player or digital picture frame, the client instructs the user to use another computer or device (a desktop computer, smart phone, or tablet) and connect to the authorization server to approve the access request. Since the client can???t receive incoming requests, it polls the authorization server repeatedly until the user completes the approval process.

The following examples show how to obtain a device code and then an access token by submitting a POST request on the REST resource using cURL. For more information about cURL, see Using cURL. See the Managing Authorization section for more information on grant types.

Note:

See Scopes for more information on using various scopes to more specifically define a set of resources and operations that an access token allows.

Note:

The command in these examples uses the URL structure https://tenant-base-url/resource-path, where tenant-base-url represents the Identity Service URL, and the resource path represents the Identity Service API. See Send Requests for the appropriate URL structure to use.

Obtain the Device Code

The following example shows an example request to obtain the device code, and then an example response that is returned:

Request Example

The device client makes an unauthenticated call to the /oauth2/v1/device endpoint:

curl -i -k
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8'
--request POST 'https://tenant-base-url/oauth2/v1/device' -d 'response_type=device_code&scope=http://tenant-base-url/quotes&client_id=<client-id>' 

Response Example

{
  "expires_in": 300,
  "device_code": "4d03f7bc-f7a5-4795-819a-5748c4801d35",
  "user_code": "SDFGHJKL",
  "verification_uri": "http://tenant-base-url/ui/v1/device"
}

Device Code Grant Type Request and Response Examples

While the user authorizes (or denies) the client's request, the client repeatedly polls the authorization server at the token endpoint (oauth2/v1/token) to find out if the user completed the user authorization step. The client includes the verification code and its client identifier in the request.

Example requests and responses are found on the Example tab of the oauth2/v1/token endpoint page.

Back to Top