> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Device API documentation for the FusionAuth Device OAuth2 endpoint. # Device 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](https://tools.ietf.org/html/rfc8628#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`Stringrequired 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`Stringrequired The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. `scope`Stringoptional 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](https://fusionauth.io/docs/apis/oauth/token.md) 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 ```plaintext 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](https://fusionauth.io/docs/apis/oauth/oauth-error.md) 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* ```json { "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](#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`Stringoptional 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](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) 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. ```plaintext 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. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired 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`Stringoptional 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`Stringoptional The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `user_code`Stringrequired 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](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Validate and retrieve a user\_code using an API key POST/oauth2/device/user-code OpenAPI Spec ### Request Headers `Content-Type`Stringrequired 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`Stringrequired 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](https://fusionauth.io/docs/apis/oauth/oauth-error.md) 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`StringAvailable 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](#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* ```json { "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`Stringrequired The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. `user_code`Stringrequired 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](https://fusionauth.io/docs/apis/oauth/oauth-error.md) 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](#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`Stringoptional 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](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) 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. ```plaintext 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. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired 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`Stringoptional 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`Stringoptional The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `token`Stringrequired 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`Stringrequired 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](https://fusionauth.io/docs/apis/oauth/oauth-error.md) 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`StringAvailable 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](https://fusionauth.io/docs/reference/data-types.md#instants) when the identity provider link was created. `identityProviderLink.lastLoginInstant`Long The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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* ```json { "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" } ```