openapi: 3.0.3 info: title: Authlete Authorization Endpoint Device Flow API description: "Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the \nplatform is configurable via API. This documentation will help you authenticate and integrate with Authlete to \nbuild powerful OAuth 2.0 and OpenID Connect servers.\n\nAt a high level, the Authlete API is grouped into two categories:\n\n- **Management APIs**: Enable you to manage services and clients.\n- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.\n\n## \U0001F310 API Servers\n\nAuthlete is a global service with clusters available in multiple regions across the world:\n\n- \U0001F1FA\U0001F1F8 **US**: `https://us.authlete.com`\n- \U0001F1EF\U0001F1F5 **Japan**: `https://jp.authlete.com`\n- \U0001F1EA\U0001F1FA **Europe**: `https://eu.authlete.com`\n- \U0001F1E7\U0001F1F7 **Brazil**: `https://br.authlete.com`\n\nOur customers can host their data in the region that best meets their requirements.\n\n## \U0001F511 Authentication\n\nAll API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n### Getting Your Access Token\n\nAuthlete supports two types of access tokens:\n\n**Service Access Token** - Scoped to a single service (authorization server instance)\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to your service → **Settings** → **Access Tokens**\n3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)\n4. Copy the generated token\n\n**Organization Token** - Scoped to your entire organization\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to **Organization Settings** → **Access Tokens**\n3. Click **Create Token** and select org-level permissions\n4. Copy the generated token\n\n> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only \n> access their specific service, while organization tokens can access all services within your org.\n\n### Token Security Best Practices\n\n- **Never commit tokens to version control** - Store in environment variables or secure secret managers\n- **Rotate regularly** - Generate new tokens periodically and revoke old ones\n- **Scope appropriately** - Request only the permissions your application needs\n- **Revoke unused tokens** - Delete tokens you're no longer using from the console\n\n### Quick Test\n\nVerify your token works with a simple API call:\n\n```bash\ncurl -X GET https://us.authlete.com/api/service/get/list \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## \U0001F393 Tutorials\n\nIf you're new to Authlete or want to see sample implementations, these resources will help you get started:\n\n- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)\n- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)\n\n## \U0001F6E0 Contact Us\n\nIf you have any questions or need assistance, our team is here to help:\n\n- [Contact Page](https://www.authlete.com/contact/)\n" version: 3.0.16 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - description: 🇺🇸 US Cluster url: https://us.authlete.com - description: 🇯🇵 Japan Cluster url: https://jp.authlete.com - description: 🇪🇺 Europe Cluster url: https://eu.authlete.com - description: 🇧🇷 Brazil Cluster url: https://br.authlete.com security: - bearer: [] tags: - name: Device Flow description: API endpoints for implementing OAuth 2.0 Device Flow x-tag-expanded: false paths: /api/{serviceId}/device/authorization: post: summary: Process Device Authorization Request description: '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. ' x-mint: metadata: description: 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. content: ' This API is supposed to be called from the within the implementation of the device authorization endpoint of the service. The service implementation should retrieve the value of `action` from the response and take the following steps according to the value. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the API call from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with "500 Internal Server Error"s and `application/json`. The value of `responseContent` is a JSON string which describes t he error, so it can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is wrong. The authorization server implementation should generate a response to the client application with "400 Bad Request" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that client authentication of the device authorization request failed. The authorization server implementation should generate a response to the client application with "401 Unauthorized" and `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: (challenge) Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## OK When the value of `action` is `OK`, it means that the device authorization request from the client application is valid. The authorization server implementation should generate a response to the client application with "200 OK" and `application/json`. The `responseContent` is a JSON string which can be used as the entity body of the response. --- The following illustrates the response which the authorization server implementation should generate and return to the client application. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/device_authorization_request' example: parameters: client_id=26888344961664&scope=history.read clientId: '26888344961664' clientSecret: SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/device_authorization_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/device_authorization_response' example: resultCode: A220001 resultMessage: '[A220001] The device authorization request was processed successfully.' action: OK clientId: 26888344961664 clientIdAliasUsed: false clientName: My Device Flow Client deviceCode: p0qzXeRav8u6lJY9omjzR47KK58VwYN7j8xGUD7sq5I expiresIn: 3600 interval: 0 responseContent: '{"user_code":"XWWKPBWVXQ","device_code":"p0qzXeRav8u6lJY9omjzR47KK58VwYN7j8xGUD7sq5I","verification_uri_complete":"https://my-service.com/df/verification?XWWKPBWVXQ","verification_uri":"https://my-service.com/df/verification","expires_in":3600}' scopes: - defaultEntry: false name: history.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value userCode: XWWKPBWVXQ verificationUri: https://my-service.com/df/verification verificationUriComplete: https://my-service.com/df/verification?XWWKPBWVXQ links: device_verify: $ref: '#/components/links/device_verification' device_poll_token: $ref: '#/components/links/device_complete' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: device_authorization_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/device/authorization \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "parameters": "client_id=26888344961664&scope=history.read", "clientId": "26888344961664", "clientSecret":"SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); DeviceAuthorizationRequest req = new DeviceAuthorizationRequest(); req.setParameters(...); req.setClientId("26888344961664"); req.setClientSecret("SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog"); api.deviceAuthorization(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = DeviceAuthorizationRequest() req.parameters = ... req.clientId = ''26888344961664'' req.clientSecret = ''SfnYOLkJdofrb_66mTd6q03_SDoDEUnpXtvqFaE4k6L6UcpZzbdVJi2GpBj48AvGeDDllwsTruC62WYqQ_LGog'' api.deviceAuthorization(req) ' tags: - Device Flow /api/{serviceId}/device/verification: post: summary: Process Device Verification Request description: 'The API returns information associated with a user code. ' x-mint: metadata: description: The API returns information associated with a user code. content: ' After receiving a response from the device authorization endpoint of the authorization server, the client application shows the end-user the user code and the verification URI which are included in the device authorization response. Then, the end-user will access the verification URI using a web browser on another device (typically, a smart phone). In normal implementations, the verification endpoint will return an HTML page with an input form where the end-user inputs a user code. The authorization server will receive a user code from the form. After receiving a user code, the authorization server should call Authlete''s `/device/verification` API with the user code. And then, the authorization server implementation should retrieve the value of `action` parameter from the API response and take the following steps according to the value. ## SERVER_ERROR When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The authorization server implementation should tell the end-user that something wrong happened and urge her to re-initiate a device flow. ## NOT_EXIST When the value of `action` is `NOT_EXIST`, it means that the user code does not exist. The authorization server implementation should tell the end-user that the user code is invalid and urge her to retry to input a valid user code. ## EXPIRED When the value of `action` is `EXPIRED`, it means that the user code has expired. The authorization server implementation should tell the end-user that the user code has expired and urge her to re-initiate a device flow. ## VALID When the value of `action` is `VALID`, it means that the user code exists, has not expired, and belongs to the service. The authorization server implementation should interact with the end-user to ask whether she approves or rejects the authorization request from the device. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/device_verification_request' example: userCode: XWWKPBWVXQ application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/device_verification_request' responses: '200': description: Device verification completed successfully content: application/json: schema: $ref: '#/components/schemas/device_verification_response' example: resultCode: A224001 resultMessage: '[A224001] The user code is valid.' action: VALID clientId: 26888344961664 clientIdAliasUsed: false clientName: My Device Flow Client expiresAt: 1642001978000 scopes: - defaultEntry: false name: history.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: device_verification_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/device/verification \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "userCode": "XWWKPBWVXQ" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); DeviceVerificationRequest req = new DeviceVerificationRequest(); req.setUserCode("XWWKPBWVXQ"); api.deviceVerification(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = DeviceVerificationRequest() req.setUserCode(''XWWKPBWVXQ'') api.deviceVerification(req) ' tags: - Device Flow /api/{serviceId}/device/complete: post: summary: Complete Device Authorization description: 'This API returns information about what action the authorization server should take after it receives the result of end-user''s decision about whether the end-user has approved or rejected a client application''s request. ' x-mint: metadata: description: This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request. content: ' In the device flow, an end-user accesses the verification endpoint of the authorization server where she interacts with the verification endpoint and inputs a user code. The verification endpoint checks if the user code is valid and then asks the end-user whether she approves or rejects the authorization request which the user code represents. After the authorization server receives the decision of the end-user, it should call Authlete''s `/device/complete` API to tell Authlete the decision. When the end-user was authenticated and authorization was granted to the client by the end-user, the authorization server should call the API with `result=AUTHORIZED`. In this successful case, the subject request parameter is mandatory. The API will update the database record so that `/auth/token` API can generate an access token later. If the `scope` parameter of the device authorization request included the openid scope, an ID token is generated. In this case, `sub`, `authTime`, `acr` and `claims` request parameters in the API call to `/device/complete` affect the ID token. When the authorization server receives the decision of the end-user and it indicates that she has rejected to give authorization to the client, the authorization server should call the API with `result=ACCESS_DENIED`. In this case, the API will update the database record so that the `/auth/token` API can generate an error response later. If `errorDescription` and `errorUri` request parameters are given to the `/device/complete` API, they will be used as the values of `error_description` and `error_uri` response parameters in the error response from the token endpoint. When the authorization server could not get decision from the end-user for some reasons, the authorization server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error` response parameter instead of `access_denied`. After receiving a response from the `/device/complete` API, the implementation of the authorization server should retrieve the value of `action` from the response and take the following steps according to the value. ## SERVER_ERROR When the value of `action` is `SERVER_ERROR`, it means that an error occurred on Authlete side. The authorization server implementation should tell the end-user that something wrong happened and urge her to re-initiate a device flow. ## USER_CODE_NOT_EXIST When the value of `action` is `USER_CODE_NOT_EXIST`, it means that the user code included in the API call does not exist. The authorization server implementation should tell the end-user that the user code has been invalidated and urge her to re-initiate a device flow. ## USER_CODE_EXPIRED When the value of `action` is `USER_CODE_EXPIRED`, it means that the user code included in the API call has expired. The authorization server implementation should tell the end-user that the user code has expired and urge her to re-initiate a device flow. ## INVALID_REQUEST When the value of `action` is `INVALID_REQUEST`, it means that the API call is invalid. Probably, the authorization server implementation has some bugs. ## SUCCESS When the value of `action` is `SUCCESS`, it means that the API call has been processed successfully. The authorization server should return a successful response to the web browser the end-user is using. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/device_complete_request' example: userCode: XWWKPBWVXQ result: AUTHORIZED subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/device_complete_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/device_complete_response' example: resultCode: A241001 resultMessage: '[A241001] The API call was processed successfully.' action: SUCCESS '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: device_complete_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/device/complete \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "userCode": "XWWKPBWVXQ", "result": "AUTHORIZED", "subject": "john" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); DeviceCompleteRequest req = new DeviceCompleteRequest(); req.setUserCode("XWWKPBWVXQ"); req.setResult(DeviceCompleteRequest.Result.AUTHORIZED); req.setSubject("john"); api.deviceComplete(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = DeviceCompleteRequest() req.setUserCode(''XWWKPBWVXQ'') req.setResult(DeviceCompleteResult.AUTHORIZED) req.setSubject(''john'') api.deviceComplete(req) ' tags: - Device Flow components: links: device_complete: operationId: device_complete_api parameters: serviceId: $request.path.serviceId device_verification: operationId: device_verification_api parameters: serviceId: $request.path.serviceId schemas: device_complete_request: type: object required: - userCode - result - subject properties: userCode: type: string description: 'A user code. ' result: type: string enum: - TRANSACTION_FAILED - ACCESS_DENIED - AUTHORIZED description: 'The result of the end-user authentication and authorization. One of the following. Details are described in the description. ' subject: type: string description: 'The subject (= unique identifier) of the end-user. ' sub: type: string description: 'The value of the sub claim that should be used in the ID token. ' authTime: type: integer format: int64 description: 'The time at which the end-user was authenticated. Its value is the number of seconds from `1970-01-01`. ' acr: type: string description: 'The reference of the authentication context class which the end-user authentication satisfied. ' claims: type: string description: 'Additional claims which will be embedded in the ID token. ' properties: type: array items: $ref: '#/components/schemas/property' description: 'The extra properties associated with the access token. ' scopes: type: array items: type: string description: 'Scopes to replace the scopes specified in the original device authorization request with. When nothing is specified for this parameter, replacement is not performed. ' errorDescription: type: string description: 'The description of the error. If this optional request parameter is given, its value is used as the value of the `error_description` property, but it is used only when the result is not `AUTHORIZED`. To comply with the specification strictly, the description must not include characters outside the set `%x20-21 / %x23-5B / %x5D-7E`. ' errorUri: type: string description: 'The URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client. ' idtHeaderParams: type: string description: 'JSON that represents additional JWS header parameters for ID tokens. ' consentedClaims: type: array items: type: string description: 'the claims that the user has consented for the client application to know. ' jwtAtClaims: type: string description: 'Additional claims that are added to the payload part of the JWT access token. ' accessTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. ' refreshTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. ' idTokenAudType: type: string description: 'The type of the `aud` claim of the ID token being issued. Valid values are as follows. | Value | Description | | ----- | ----------- | | "array" | The type of the aud claim is always an array of strings. | | "string" | The type of the aud claim is always a single string. | | null | The type of the aud claim remains the same as before. | This request parameter takes precedence over the `idTokenAudType` property of the service. ' tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. device_complete_response: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. action: type: string enum: - SERVER_ERROR - USER_CODE_NOT_EXIST - USER_CODE_EXPIRED - INVALID_REQUEST - SUCCESS description: 'The next action that the authorization server implementation should take. ' device_verification_response: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. action: type: string enum: - INTERNAL_SERVER_ERROR - NOT_EXIST - EXPIRED - VALID description: The next action that the authorization server implementation should take. clientId: type: integer format: int64 description: 'The client ID of the client application to which the user code has been issued. ' clientIdAlias: type: string description: 'The client ID alias of the client application to which the user code has been issued. ' clientIdAliasUsed: type: boolean description: '`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: type: string description: 'The name of the client application to which the user code has been issued. ' scopes: type: array items: $ref: '#/components/schemas/scope' description: 'The scopes requested by the device authorization request. Note that `description` property and `descriptions` property of each scope object in the array contained in this property is always null even if descriptions of the scopes are registered. ' claimNames: type: array items: type: string description: '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. This property is always `null` if the `scope` request parameter of the device authorization request does not include the `openid` scope even if special scopes (such as `profile`) are included in the request (unless the openid scope is included in the default set of scopes which is used when the `scope` request parameter is omitted). ' acrs: type: array items: type: string description: 'The list of ACR values requested by the device authorization request. ' resources: type: array items: type: string description: 'The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. ' authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of this service that the client application belongs to. ' clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of the client. ' dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: 'The dynamic scopes which the client application requested by the scope request parameter. ' expiresAt: type: integer format: int64 description: 'Get the date in milliseconds since the Unix epoch (1970-01-01) at which the user code will expire. ' gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: '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: $ref: '#/components/schemas/grant' grantSubject: type: string description: '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: type: string description: 'The entity ID of the client. ' clientEntityIdUsed: type: boolean description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made. ' metadataDocumentLocation: type: string format: uri description: '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: type: boolean description: '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. ' property: type: object properties: key: type: string description: The key part. value: type: string description: The value part. hidden: type: boolean description: 'The flag to indicate whether this property hidden from or visible to client applications. If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications. ' grant_management_action: type: string description: '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). ' enum: - CREATE - QUERY - REPLACE - REVOKE - MERGE grant_scope: type: object properties: scope: type: string description: 'Space-delimited scopes. ' resource: type: array items: type: string description: 'List of resource indicators. ' device_verification_request: type: object required: - userCode properties: userCode: type: string description: 'A user code. ' device_authorization_response: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. action: type: string enum: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: '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: type: integer format: int64 description: 'The client ID of the client application that has made the device authorization request. ' clientIdAlias: type: string description: 'The client ID alias of the client application that has made the device authorization request. ' clientIdAliasUsed: type: boolean description: '`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: type: string description: 'The name of the client application which has made the device authorization request. ' clientAuthMethod: type: string description: 'The client authentication method that should be performed at the device authorization endpoint. ' scopes: type: array items: $ref: '#/components/schemas/scope' description: 'The scopes requested by the device authorization request. ' x-mint: metadata: description: The scopes requested by the device authorization request. content: ' Basically, this property holds the value of the scope request parameter in the device authorization request. However, because unregistered scopes are dropped on Authlete side, if the `scope` request parameter contains unknown scopes, the list returned by this property becomes different from the value of the `scope` request parameter. Note that `description` property and `descriptions` property of each scope object in the array contained in this property is always `null` even if descriptions of the scopes are registered. ' claimNames: type: array items: type: string description: '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: type: array items: type: string description: '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: type: string description: 'The device verification code. This corresponds to the `device_code` property in the response to the client. ' userCode: type: string description: 'The end-user verification code. This corresponds to the `user_code` property in the response to the client. ' verificationUri: type: string description: 'The end-user verification URI. This corresponds to the `verification_uri` property in the response to the client. ' verificationUriComplete: type: string description: '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: type: integer format: int32 description: 'The duration of the device verification code in seconds. This corresponds to the `expires_in` property in the response to the client. ' interval: type: integer format: int32 description: '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: type: array items: type: string description: 'The warnings raised during processing the backchannel authentication request. ' resources: type: array items: type: string description: 'The resources specified by the `resource` request parameters. See "Resource Indicators for OAuth 2.0" for details. ' authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of this service that the client application belongs to. ' clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of the client. ' dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: 'The dynamic scopes which the client application requested by the scope request parameter. ' gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: '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: $ref: '#/components/schemas/grant' grantSubject: type: string description: '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: type: string description: 'The entity ID of the client. ' clientEntityIdUsed: type: boolean description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made. ' metadataDocumentLocation: type: string format: uri description: '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: type: boolean description: '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. ' authz_details: type: object description: '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". ' properties: elements: type: array items: $ref: '#/components/schemas/authorization_details_element' description: 'Elements of this authorization details. ' authorization_details_element: type: object required: - type properties: type: type: string description: '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: type: array items: type: string description: '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: type: array items: type: string description: '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: type: array items: type: string description: '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: type: string description: '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: type: array items: type: string description: '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: type: string description: '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. ' result: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. device_authorization_request: type: object required: - parameters properties: parameters: type: string description: '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: type: string description: '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: type: string description: '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: type: string description: 'The client certificate used in the TLS connection between the client application and the device authorization endpoint of the authorization server. ' clientCertificatePath: type: array items: type: string description: 'The client certificate path presented by the client during client authentication. Each element is a string in PEM format. ' oauthClientAttestation: type: string description: '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: type: string description: '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: $ref: '#/components/schemas/cimd_options' description: '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. ' scope: type: object properties: name: type: string description: The name of the scope. defaultEntry: type: boolean description: '`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: type: string description: The description about the scope. descriptions: type: array description: The descriptions about this scope in multiple languages. items: $ref: '#/components/schemas/tagged_value' attributes: type: array description: The attributes of the scope. items: $ref: '#/components/schemas/pair' pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. cimd_options: type: object description: '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. ' properties: alwaysRetrieved: type: boolean description: '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: type: boolean description: '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: type: boolean description: '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`). ' grant: type: object properties: scopes: type: array items: $ref: '#/components/schemas/grant_scope' claims: type: array items: type: string description: 'The claims associated with the Grant. ' authorizationDetails: $ref: '#/components/schemas/authz_details' dynamic_scope: type: object properties: name: type: string description: The scope name. value: type: string description: The scope value. responses: '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.' securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT description: 'Authenticate every request with a **Service Access Token** or **Organization Token**. Set the token value in the `Authorization: Bearer ` header. **Service Access Token**: Scoped to a single service. Use when automating service-level configuration or runtime flows. **Organization Token**: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically. Both token types are issued by the Authlete console or provisioning APIs. '