REST API for Oracle Identity Cloud Service

Generate Device Code and User Code (OAuth Device Flow)

post

/oauth2/v1/device

Request

Supported Media Types

application/x-www-form-urlencoded

Root Schema : schema

Type: object

Show Source

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

{
    "type":"object",
    "properties":{
        "response_type":{
            "description":"Type of response from the server (device_code)",
            "type":"string",
            "example":"device_code"
        },
        "scope":{
            "description":"Scope for which the Device Code and User Code is requested.",
            "type":"string",
            "example":"http://abccorp.com/quote"
        },
        "client_id":{
            "description":"Unique ID of the client.",
            "type":"string",
            "example":"a5bf5db7f6c43b47b1eae399c68319c4"
        }
    },
    "required":[
        "response_type",
        "scope",
        "client_id"
    ]
}

Response

Supported Media Types

application/json

200 Response

Device Code and User Code generated

Root Schema : device

Type: object

Generated Device Code and User Code (OAuth Device Flow)

Show Source

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.

{
    "description":"Generated Device Code and User Code (OAuth Device Flow)",
    "type":"object",
    "properties":{
        "device_code":{
            "type":"string",
            "description":"Device Code used to obtain the Access Token"
        },
        "expires_in":{
            "type":"number",
            "description":"Expiry time of the Device Code and User Code in seconds"
        },
        "user_code":{
            "type":"string",
            "description":"User Code used by user to approve OAuth Device Flow."
        },
        "verification_uri":{
            "type":"string",
            "description":"Verification URI where User authenticates and approves User Code."
        }
    },
    "required":[
        "device_code",
        "expires_in",
        "user_code",
        "verification_uri"
    ]
}

400 Response

Invalid request

Root Schema : error

Type: object

Error message that appears during Revoke Refresh Token

Show Source

error: string

Error values based on the OAuth specification
error_description: string

Detailed error messages

{
    "description":"Error message that appears during Revoke Refresh Token",
    "type":"object",
    "properties":{
        "error":{
            "type":"string",
            "description":"Error values based on the OAuth specification"
        },
        "error_description":{
            "type":"string",
            "description":"Detailed error messages"
        }
    },
    "required":[
        "error",
        "error_description"
    ]
}

401 Response

Unauthorized client

Root Schema : error

Type: object

Error message that appears during Revoke Refresh Token

Show Source

error: string

Error values based on the OAuth specification
error_description: string

Detailed error messages

{
    "description":"Error message that appears during Revoke Refresh Token",
    "type":"object",
    "properties":{
        "error":{
            "type":"string",
            "description":"Error values based on the OAuth specification"
        },
        "error_description":{
            "type":"string",
            "description":"Detailed error messages"
        }
    },
    "required":[
        "error",
        "error_description"
    ]
}

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.