/Docs

Device

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-TypeStringrequired

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_idStringrequired

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

scopeStringoptional

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

CodeDescription
200The request was successful.
400The 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.
500There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

device_codeString

The device verification code.

expires_inInteger

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

intervalInteger

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

user_codeString

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_uriString

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_completeString

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#

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#

AuthorizationStringoptional

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-TypeStringrequired

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_idStringoptional

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_secretStringoptional

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

user_codeStringrequired

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.

API Key Authentication
Validate and retrieve a user_code using an API key
POST/oauth2/device/user-code
OpenAPI Spec

Request Headers#

Content-TypeStringrequired

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_codeStringrequired

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

CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401The provided client credentials are invalid, or the API key if provided is not valid.
500There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

client_idString

The unique client identifier provided on the Device Authorize request.

deviceInfo.descriptionString

The optional device description provided on the Device Authorize request.

deviceInfo.nameString

The optional device name provided on the Device Authorize request.

deviceInfo.typeString

The optional device type provided on the Device Authorize request.

expires_inInteger

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.displayNameString

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.identityProviderIdString

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.identityProviderNameString

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.identityProviderTypeString

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.identityProviderUserIdString

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.

scopeStringAvailable 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
tenantIdUUID

The unique Id of the Tenant.

user_codeString

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#

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_idStringrequired

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

user_codeStringrequired

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

CodeDescription
200The request was successful. No response body will be returned on successful validation.
400The 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.
500There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Device Approve#

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#

AuthorizationStringoptional

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-TypeStringrequired

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_idStringoptional

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_secretStringoptional

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

tokenStringrequired

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_codeStringrequired

The end-user verification code.

Response#

Response Codes

CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401The client could not be verified. Verify your client_id and client_secret are valid and authorized for this request.
500There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files.

Response Body#

deviceGrantStatusString

The device grant status. This will always be Approved.

deviceInfo.descriptionString

The optional device description provided on the Device Authorize request.

deviceInfo.nameString

The optional device name provided on the Device Authorize request.

deviceInfo.typeString

The optional device type provided on the Device Authorize request.

identityProviderLink.displayNameString

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.identityProviderIdString

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.identityProviderNameStringAvailable 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.identityProviderTypeString

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.identityProviderUserIdString

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.insertInstantLong

The instant when the identity provider link was created.

identityProviderLink.lastLoginInstantLong

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

tenantIdUUID

The unique Id of the Tenant.

userIdUUID

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"
}