Generate Device Code and User Code (OAuth Device Flow)
/oauth2/v1/device
Request
- application/x-www-form-urlencoded
object
-
client_id:
string
Unique ID of the client.Example:
a5bf5db7f6c43b47b1eae399c68319c4
-
response_type:
string
Type of response from the server (device_code)Example:
device_code
-
scope:
string
Scope for which the Device Code and User Code is requested.Example:
http://abccorp.com/quote
Response
- application/json
200 Response
object
-
device_code:
string
Device Code used to obtain the Access Token
-
expires_in:
number
Expiry time of the Device Code and User Code in seconds
-
user_code:
string
User Code used by user to approve OAuth Device Flow.
-
verification_uri:
string
Verification URI where User authenticates and approves User Code.
400 Response
object
-
error:
string
Error values based on the OAuth specification
-
error_description:
string
Detailed error messages
401 Response
object
-
error:
string
Error values based on the OAuth specification
-
error_description:
string
Detailed error messages
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 structurehttps://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.