Device

Edit on GitHubEdit MD

version

This endpoint been available since 1.11.0

This is an implementation of the Device Authorization endpoint as defined by the IETF RFC 8628 Section 3.1.

Device Authorize#

To begin the Device Authorization Grant you will make a request to the Device Authorization endpoint from the device.

POST/oauth2/device_authorize

OpenAPI Spec

Request Headers#

Content-Type String required

This value must be set to application/x-www-form-urlencoded.

Request Parameters#

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id String required

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

scope String optional

This parameter may contain multiple scopes space separated. For example, the value of openid offline_access provides two scopes on the request.

These scopes modify the behavior of the endpoint:

openid - This scope is used to request an id_token be returned in the response
offline_access - This scope is used to request a refresh_token be returned in the eventual Token response.
idp-link - This scope is used to begin a linking request from a game console.

Supported console links include Epic, Nintendo, Sony Playstation Network, Steam, and Xbox.

This scope format is as follows: idp-link:{identityProviderId}:{token}. When this scope is provided on the request, the token will be verified and when the device grant is complete, a link will be established between the FusionAuth user and the user represented by the provided token. If you need to send more than one token, separate each token using a colon character :. Here is an example format when more than one token is required: idp-link:{identityProviderId}:{token1}:{token2}.

Example HTTP Request

POST /oauth2/device_authorize HTTP/1.1
Host: piedpiper.fusionauth.io
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 436
client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&scope=offline_access

Response#

Response Codes

Code	Description
200	The request was successful.
400	The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

device_code String

The device verification code.

expires_in Integer

The number of seconds the device_code and user_code tokens returned in the response will remain active.

interval Integer

The minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.

user_code String

The end-user verification code. This value will generally be displayed on the device for the user to read and enter into an activation form.

verification_uri String

The end-user verification URI on the authorization server. This value will generally be displayed on the device to instruct the user where to navigate in order to find the form where they may enter the provided user_code.

verification_uri_complete String

A verification URI that includes the user_code. This is the same value as returned in the verification_uri with the user_code appended as a request parameter. This can be used to build a QR code or provide a clickable link that may pre-populate a form with the user_code.

Example JSON Response

{
  "device_code": "e6f_lF1rG_yroI0DxeQB5OrLDKU18lrDhFXeQqIKAjg",
  "expires_in": 600,
  "interval": 5,
  "user_code": "FBGLLF",
  "verification_uri": "https://piedpiper.com/device",
  "verification_uri_complete": "https://piedpiper.com/device?user_code=FBGLLF"
}

Device User Code#

version

This endpoint has been available since 1.46.0

This endpoint is intended to validate the end-user provided user_code and return meta-data useful when building your own interactive workflow.

This endpoint is equivalent to the Device Validate endpoint, but it will return meta-data for the user_code in a JSON body.

Validate and retrieve a user_code using client credentials

POST/oauth2/device/user-code

OpenAPI Spec

Request Headers#

Authorization String optional

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Please see the Client Secret section for more details. If providing client authentication using the Basic Authentication Scheme authorization header, the value is created by taking the clientId and clientSecret properties defined in the Application OAuth Configuration and concatenating them together using a : character.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

Content-Type String required

This value must be set to application/x-www-form-urlencoded.

Request Parameters#

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id String optional

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is then required. Prior to version 1.46.0 this parameter was always required.

client_secret String optional

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

user_code String required

The end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.

Validate and retrieve a user_code using an API key

POST/oauth2/device/user-code

OpenAPI Spec

Request Headers#

Content-Type String required

This value must be set to application/x-www-form-urlencoded.

Request Parameters#

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

user_code String required

The end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.

Response#

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation.
401	The provided client credentials are invalid, or the API key if provided is not valid.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

client_id String

The unique client identifier provided on the Device Authorize request.

deviceInfo.description String

The optional device description provided on the Device Authorize request.

deviceInfo.name String

The optional device name provided on the Device Authorize request.

deviceInfo.type String

The optional device type provided on the Device Authorize request.

expires_in Integer

The number of seconds the device_code and user_code tokens will remain active.

This is how long you have to complete the Device grant.

pendingIdPLink.displayName String

The human readable name of the user represented by the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

pendingIdPLink.identityProviderId String

The unique Identity Provider Id associated with the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

pendingIdPLink.identityProviderName String

The name of the Identity Provider associated with the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

pendingIdPLink.identityProviderType String

The type of the Identity Provider associated with the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

pendingIdPLink.identityProviderUserId String

The unique user Id of the user represented by the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

This value is a unique Id that links a FusionAuth user to a user in a third-party identity provider.

scope String Available since 1.50.0

The value that should be used for the scope parameter during the interactive portion of the Device Code Grant. The value contains the same scopes as the Device Authorize request with the following scopes excluded:

openid
offline_access
idp-link: prefixed scopes

tenantId UUID

The unique Id of the Tenant.

user_code String

The end-user verification code. This is the same value that was provided in the request body.

Example JSON Response

{
  "client_id": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "deviceInfo": {
    "description": "Johny's Xbox",
    "name": "Xbox",
    "type": "Console"
  },
  "expires_in": 600,
  "pendingIdPLink": {
    "displayName": "jmoney42",
    "identityProviderId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2",
    "identityProviderName": "Xbox",
    "identityProviderType": "Xbox",
    "identityProviderUserId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2"
  },
  "scope": "email profile",
  "tenantId": "5f35237d-d036-4aaa-a917-17039d4697e6",
  "user_code": "FBGLLF"
}

Device Validate#

version

This endpoint has been available since 1.11.0

This endpoint validates the end-user provided user_code from the user-interaction of the Device Authorization Grant.

If you build your own activation form you should validate the user provided code prior to beginning the Authorization grant. If you choose to redirect to the FusionAuth provided form /oauth2/device then it is not necessary for you to validate the user_code.

GET/oauth2/device/validate?client_id={client_id}&user_code={user_code}

OpenAPI Spec

Request Parameters#

client_id String required

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

user_code String required

The end-user verification code. This is the code that a user entered during the Device Authorization grant which you are requesting to be validated.

Response#

Response Codes

Code	Description
200	The request was successful. No response body will be returned on successful validation.
400	The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Device Approve#

version

This endpoint has been available since 1.46.0

Approve a user_code returned from the Device Authorize. If you are using the FusionAuth themed page for /oauth2/device you do not need to use this because the grant will be automatically approved once the user has completed authentication and the OAuth2 Grant has completed.

If you are building your own integration to collect the user_code from the end user, and wish to approve the Device Grant after authenticating the user, use this API to approve the device code allowing the Device Grant to complete.

POST/oauth2/device/approve

OpenAPI Spec

Request Headers#

Authorization String optional

This header is optional if you have provided the client_id in the request body.

The client_secret may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the client_secret must be valid.

Here is an example of these two values concatenated.

463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892

This value is then Base64 encoded and prepended with the string Basic to denote the schema type. The following is an example Authorization header using the example concatenation above.

Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI=

The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different.

Content-Type String required

This value must be set to application/x-www-form-urlencoded.

Request Parameters#

Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string.

client_id String optional

The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate.

This parameter is optional when the Authorization header is provided. When the Authorization header is not provided, this parameter is then required. Prior to version 1.3.1 this parameter was always required.

client_secret String optional

The client secret. This parameter is optional when the Authorization header is provided. Please see the the Client Secret table for more details.

token String required

The access token returned by this OAuth provider as the result of a successful authentication. This token must contain a sub claim which will be used to identify the FusionAuth User.

user_code String required

The end-user verification code.

Response#

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the OAuth Error section of the API documentation.
401	The client could not be verified. Verify your `client_id` and `client_secret` are valid and authorized for this request.
500	There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

deviceGrantStatus String

The device grant status. This will always be Approved.

deviceInfo.description String

The optional device description provided on the Device Authorize request.

deviceInfo.name String

The optional device name provided on the Device Authorize request.

deviceInfo.type String

The optional device type provided on the Device Authorize request.

identityProviderLink.displayName String

The human readable name of the user represented by the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

identityProviderLink.identityProviderId String

The unique Identity Provider Id associated with the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

identityProviderLink.identityProviderName String Available since 1.47.0

The name of the Identity Provider associated with the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

identityProviderLink.identityProviderType String

The type of the Identity Provider associated with the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

identityProviderLink.identityProviderUserId String

The unique user Id of the user represented by the linking token provided in the idp-link: scope value optionally provided on the Device Authorize request.

This value is a unique Id that links a FusionAuth user to a user in a third-party identity provider.

identityProviderLink.insertInstant Long

The instant when the identity provider link was created.

identityProviderLink.lastLoginInstant Long

The instant when the User logged in last using this identity provider.

tenantId UUID

The unique Id of the Tenant.

userId UUID

The unique Id of the User.

Example JSON Response

{
  "deviceGrantStatus": "Approved",
  "deviceInfo": {
    "description": "Johny's Xbox",
    "name": "Xbox",
    "type": "Console"
  },
  "identityProviderLink": {
    "displayName": "jmoney42",
    "identityProviderId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2",
    "identityProviderName": "Xbox",
    "identityProviderType": "Xbox",
    "identityProviderUserId": "af53ab21-34c3-468a-8ba2-ecb3905f67f2"
  },
  "tenantId": "5f35237d-d036-4aaa-a917-17039d4697e6",
  "userId": "3b6d2f70-4821-4694-ac89-60333c9c4165"
}