--- title: Device authorization endpoint description: The device authorization endpoint allows a user to grant authorization to a device client using a browser on a second device, such as a smart phone or a computer. component: pingfederate version: 13.0 page_id: pingfederate:developers_reference_guide:pf_device_auth_endpoint canonical_url: https://docs.pingidentity.com/pingfederate/13.0/developers_reference_guide/pf_device_auth_endpoint.html revdate: March 20, 2023 section_ids: endpoint-asdevice_authz-oauth2: "Endpoint: /as/device_authz.oauth2" example-request: Example request exampleresponse-codes-and-example-responses: ExampleResponse codes and example responses oauth-client-identification-and-authentication: OAuth client identification and authentication related-links: Related links --- # Device authorization endpoint The device authorization endpoint allows a user to grant authorization to a device client using a browser on a second device, such as a smart phone or a computer. The [OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628) defines the device authorization endpoint. Based on the specification, the device sends a device authorization request to PingFederate, the authorization server (AS), at its device authorization endpoint. | | | | - | -------------------------------------------------------------------------- | | | Per OAuth specifications, this endpoint accepts only the HTTP POST method. | ## Endpoint: /as/device\_authz.oauth2 The required `Content-Type` value is `application/x-www-form-urlencoded`. The following table describes parameters for this endpoint. | Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | A unique identifier the client provides to the resource server *(tooltip: \
\

In OAuth 2.0, a server that hosts protected resources and can accept and respond to resource requests from clients presenting a valid access token.\

\
)* to identify itself. This identifier is included with every request the client makes | | `scope`(Optional) | The scope of the access request expressed as a list of space-delimited, case-sensitive strings.Scopes can also be constrained on a client-to-client basis. For more information about scopes, see [Scopes and scope management](../administrators_reference_guide/pf_scopes_and_scope_management.html). | Both the request and the response follow the [OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/draft-ietf-oauth-device-flow). ## Example request ``` POST /as/device_authz.oauth2 HTTP/1.1 Content-Type: application/x-www-form-urlencoded Host: www.example.com ... client_id=df_client ``` ## ExampleResponse codes and example responses 200 - Success ``` HTTP/1.1 200 OK ... { "user_code": "YYD6-CD4T", "device_code": "4EHsIngavzIPvvqMlFgQlseTCsH7EpU75f9yGvj60T", "interval": 5, "verification_uri_complete": "https://www.example.com/as/user_authz.oauth2?user_code=YYD6-CD4T", "verification_uri": "https://www.example.com/as/user_authz.oauth2", "expires_in": 600 } ``` 400 - Bad Request ``` HTTP/1.1 400 Bad Request ... { "error_description": "The requested scope(s) must be blank or a subset of the provided scopes.", "error": "invalid_scope" } ``` 401 - Unauthorized ``` HTTP/1.1 401 Unauthorized ... { "error_description": "Invalid client or client credentials.", "error": "invalid_client" } ``` ## OAuth client identification and authentication The authentication requirement of this endpoint depends on the client authentication method configured for the clients. | Authentication method | Parameters | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Client secret | Clients can present their client identifier and client secret using the HTTP Basic authentication scheme, where the client identifier is the username, and the client secret is the password.Clients can provide credentials using the request parameters `client_id` and `client_secret`. This is a sensitive parameter. To avoid recording it in web server logs, only pass in this parameter with the HTTP POST method in the message body, or through the HTTP Basic authentication scheme. | | Client certificate | Clients must present their client certificate for mutual TLS authentication. The issuer and the subject distinguished name (DN) of the client certificate must match values configured for the clients. | | Private key JWT or Client Secret JWT | Clients must include request parameters `client_assertion_type` and `client_assertion` in the message body of their requests.- `client_assertion_type` The value describes the format of the assertion as defined by the authorization server. For the private\_key\_jwt and client\_secret\_jwt client authentication methods, the value is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. - `client_assertion` The value is the authentication token.**Example**``` ... client_assertion_type= urn%3Aietf%3Aparams%3Aoauth% 3Aclient-assertion-type%3Ajwt-bearer& client_assertion= eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg& ... ``` For readability, line breaks are inserted and the authentication token is truncated.Learn more about the private\_key\_jwt and client\_secret\_jwt client authentication methods in [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) and [Using Assertions for Client Authentication](https://datatracker.ietf.org/doc/html/rfc7521/#autoid-7). | | None | Clients must pass in the `client_id` parameter in a query string or the message body to identify themselves. | ## Related links * [Device authorization grant](../introduction_to_pingfederate/pf_device_auth_grant.html) * [Configuring authorization server settings](../administrators_reference_guide/help_authorizationserversettingstasklet_oauthauthorizationserversettingsstate.html)