---
title: "Process Device Authorization Request"
method: POST
path: "/api/{serviceId}/device/authorization"
tags: ["Device Flow"]
---

# Process Device Authorization Request

`POST /api/{serviceId}/device/authorization`

This API parses request parameters of a [device authorization request](https://datatracker.ietf.org/doc/html/rfc8628#section-3.1)
and returns necessary data for the authorization server implementation to process the device authorization
request further.

## Path parameters

- `serviceId` string, required

## Request body

- DeviceAuthorizationRequest
  - `parameters` string, required — Parameters of a device authorization request which are the request parameters that the device authorization endpoint of the authorization server implementation received from the client application. The value of `parameters` is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the request from the client application.
  - `clientId` string — The client ID extracted from Authorization header of the device authorization request from the client application. If the device authorization endpoint of the authorization server implementation supports Basic `Authentication` as a means of client authentication, and the request from the client application contained its client ID in `Authorization` header, the value should be extracted and set to this parameter.
  - `clientSecret` string — The client secret extracted from `Authorization` header of the device authorization request from the client application. If the device authorization endpoint of the authorization server implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in `Authorization` header, the value should be extracted and set to this parameter.
  - `clientCertificate` string — The client certificate used in the TLS connection between the client application and the device authorization endpoint of the authorization server.
  - `clientCertificatePath` string[] — The client certificate path presented by the client during client authentication. Each element is a string in PEM format.
  - `oauthClientAttestation` string — The value of the `OAuth-Client-Attestation` HTTP header, which is defined in the specification of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).
  - `oauthClientAttestationPop` string — The value of the `OAuth-Client-Attestation-PoP` HTTP header, which is defined in the specification of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/).
  - `cimdOptions` CimdOptions — Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided.
    - `alwaysRetrieved` boolean — Whether to always retrieve client metadata in the CIMD context regardless of the cache's validity. Under normal circumstances, client metadata retrieved from the location referenced by the client ID is stored in the database with an expiration time calculated using HTTP caching mechanisms (see [RFC 9111 HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html)). Until that expiration time is reached, Authlete does not attempt to retrieve the client metadata again. When this flag is set to `true`, Authlete retrieves the client metadata regardless of the cache's validity. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdAlwaysRetrieved`). This flag is effective only when the service supports CIMD (see `Service.clientIdMetadataDocumentSupported`) and CIMD is actually used to resolve client metadata. For example, if the client ID in a request does not appear to be a valid URI, CIMD will not be used even if the service is configured to support it. In such cases, this flag has no effect. Client metadata retrieval is performed only in the initiating request of an authorization flow, and not in any subsequent requests. For example, in the authorization code flow, metadata may be retrieved during the authorization request, but not during the subsequent token request. In contrast, in the client credentials flow, metadata retrieval may occur because the token request itself is the initiating request in the flow.
    - `httpPermitted` boolean — Whether to allow the `http` scheme in client IDs in the CIMD context. The specification requires the `https` scheme, but if this flag is set to `true`, Authlete also allows the `http` scheme. The main purpose of this option is to make development easier for developers who run CIMD-enabled servers and a web server publishing client metadata on their local machines without TLS. Given this purpose, it is not recommended to enable this option in production environments unless an allowlist is used (see `Service.cimdAllowlistEnabled`). If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdHttpPermitted`).
    - `queryPermitted` boolean — Whether to allow a query component in client IDs in the CIMD context. Although the specification states that a client ID "SHOULD NOT include a query string component," it does technically allow it. However, query components are prone to misuse. Therefore, Authlete does not allow them by default. Setting this flag to `true` relaxes that restriction. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdQueryPermitted`).

## Response `200`

- DeviceAuthorizationResponse
  - `resultCode` string — The code which represents the result of the API call.
  - `resultMessage` string — A short message which explains the result of the API call.
  - `action` 'INTERNAL_SERVER_ERROR' | 'BAD_REQUEST' | 'UNAUTHORIZED' | 'OK' — The next action that the authorization server implementation should take.
  - `responseContent` string — The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter.
  - `clientId` integer — The client ID of the client application that has made the device authorization request.
  - `clientIdAlias` string — The client ID alias of the client application that has made the device authorization request.
  - `clientIdAliasUsed` boolean — `true` if the value of the client_id request parameter included in the device authorization request is the client ID alias. `false` if the value is the original numeric client ID.
  - `clientName` string — The name of the client application which has made the device authorization request.
  - `clientAuthMethod` string — The client authentication method that should be performed at the device authorization endpoint.
  - `scopes` Scope[] — The scopes requested by the device authorization request.
    - `name` string — The name of the scope.
    - `defaultEntry` boolean — `true` to mark the scope as default. Scopes marked as default are regarded as requested when an authorization request from a client application does not contain scope request parameter.
    - `description` string — The description about the scope.
    - `descriptions` TaggedValue[] — The descriptions about this scope in multiple languages.
      - `tag` string — The language tag part.
      - `value` string — The value part.
    - `attributes` Pair[] — The attributes of the scope.
      - `key` string — The key part.
      - `value` string — The value part.
  - `claimNames` string[] — The names of the claims which were requested indirectly via some special scopes. See [5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) in OpenID Connect Core 1.0 for details.
  - `acrs` string[] — The list of ACR values requested by the device authorization request. Basically, this property holds the value of the `acr_values` request parameter in the device authorization request. However, because unsupported ACR values are dropped on Authlete side, if the `acr_values` request parameter contains unrecognized ACR values, the list returned by this property becomes different from the value of the `acr_values` request parameter.
  - `deviceCode` string — The device verification code. This corresponds to the `device_code` property in the response to the client.
  - `userCode` string — The end-user verification code. This corresponds to the `user_code` property in the response to the client.
  - `verificationUri` string — The end-user verification URI. This corresponds to the `verification_uri` property in the response to the client.
  - `verificationUriComplete` string — The end-user verification URI that includes the end-user verification code. This corresponds to the `verification_uri_complete` property in the response to the client.
  - `expiresIn` integer — The duration of the device verification code in seconds. This corresponds to the `expires_in` property in the response to the client.
  - `interval` integer — The minimum amount of time in seconds that the client must wait for between polling requests to the token endpoint. This corresponds to the `interval` property in the response to the client.
  - `warnings` string[] — The warnings raised during processing the backchannel authentication request.
  - `resources` string[] — The resources specified by the `resource` request parameters. See "Resource Indicators for OAuth 2.0" for details.
  - `authorizationDetails` AuthzDetails — The authorization details. This represents the value of the `authorization_details` request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests".
    - `elements` AuthorizationDetailsElement[] — Elements of this authorization details.
      - `type` string, required — The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`.
      - `locations` string[] — The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`.
      - `actions` string[] — The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`.
      - `dataTypes` string[] — From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`.
      - `identifier` string — The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`.
      - `privileges` string[] — The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`.
      - `otherFields` string — The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented.
  - `serviceAttributes` Pair[] — The attributes of this service that the client application belongs to.
    - `key` string — The key part.
    - `value` string — The value part.
  - `clientAttributes` Pair[] — The attributes of the client.
    - `key` string — The key part.
    - `value` string — The value part.
  - `dynamicScopes` DynamicScope[] — The dynamic scopes which the client application requested by the scope request parameter.
    - `name` string — The scope name.
    - `value` string — The scope value.
  - `gmAction` 'CREATE' | 'QUERY' | 'REPLACE' | 'REVOKE' | 'MERGE' — The grant management action of the device authorization request. The `grant_management_action` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html).
  - `grantId` string — the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions.
  - `grant` Grant
    - `scopes` GrantScope[]
      - `scope` string — Space-delimited scopes.
      - `resource` string[] — List of resource indicators.
    - `claims` string[] — The claims associated with the Grant.
    - `authorizationDetails` AuthzDetails — The authorization details. This represents the value of the `authorization_details` request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests".
      - `elements` AuthorizationDetailsElement[] — Elements of this authorization details.
        - `type` string, required — The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`.
        - `locations` string[] — The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`.
        - `actions` string[] — The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`.
        - `dataTypes` string[] — From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`.
        - `identifier` string — The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`.
        - `privileges` string[] — The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`.
        - `otherFields` string — The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented.
  - `grantSubject` string — The subject identifying the user who has given the grant identified by the `grant_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer's draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the `subject` passed to Authlete does not match the user of the grant.
  - `clientEntityId` string — The entity ID of the client.
  - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made.
  - `metadataDocumentLocation` string, uri — The location of the client's metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism.
  - `metadataDocumentUsed` boolean — Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database.

## Other responses

- `400`
- `401`
- `403`
- `429` — The request exceeded the request rate permitted for the endpoint.
- `500`

## Changes

- **2026-08-03** `7ad74ab64749` — 1 info
  - added the non-success response with the status `429`
- **2025-12-18** `504771740022` — 4 info
  - added the new optional request property `cimdOptions` (media type: application/json)
  - added the new optional request property `cimdOptions` (media type: application/x-www-form-urlencoded)
  - added the optional property `metadataDocumentLocation` to the response with the `200` status
  - added the optional property `metadataDocumentUsed` to the response with the `200` status

[Change history](https://skmtc.dev/authlete/apis/authlete-api/changes/api/:serviceId/device/authorization/post.md)

---

[API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/7ad74ab64749/schema)