openapi: 3.0.3
info:
  title: Authlete Authorization Endpoint UserInfo Endpoint 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: UserInfo Endpoint
  description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
  x-tag-expanded: false
paths:
  /api/{serviceId}/auth/userinfo:
    post:
      summary: Process UserInfo Request
      description: 'This API gathers information about a user.

        '
      x-mint:
        metadata:
          description: This API gathers information about a user.
        content: '<Accordion title="Full description" defaultOpen={false}>

          This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)

          of the authorization server in order to get information about the user that is associated with

          an access token.

          The response from `/auth/userinfo` API has various parameters. Among them, it is `action` parameter

          that the authorization server implementation should check first because it denotes the next action

          that the authorization server implementation should take. According to the value of `action`, the

          service implementation must take the steps described below.


          ## INTERNAL_SERVER_ERROR


          When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization

          server implementation was wrong or that an error occurred in Authlete. In either case, from the

          viewpoint of the client application, it is an error on the server side. Therefore, the service

          implementation should generate a response to the client application with HTTP status of "500 Internal

          Server Error".

          The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)

          (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`

          as the value of`WWW-Authenticate` header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 500 Internal Server Error

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## BAD_REQUEST


          When the value of `action` is `BAD_REQUEST`, it means that the request from the client application

          does not contain an access token (= the request from the authorization server implementation to

          Authlete does not contain `token` parameter).

          The value of `responseContent` is a string which describes the error in the format

          of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the

          userinfo endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`

          header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 400 Bad Request

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## UNAUTHORIZED


          When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has

          expired, or is not associated with any subject (= any user account).

          The value of `responseContent` is a string which describes the error in the format of [RFC

          6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo

          endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`

          header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 401 Unauthorized

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## FORBIDDEN


          When the value of `action` is `FORBIDDEN`, it means that the access token does not include the

          `openid` scope.

          The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)

          (OAuth 2.0 Bearer Token Usage) so the userinfo endpoint implementation can use the value of `responseContent`

          as the value of`WWW-Authenticate` header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 403 Forbidden

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## OK


          When the value of `action` is `OK`, it means that the access token which the client application

          presented is valid. To be concrete, it means that the access token exists, has not expired, includes

          the openid scope, and is associated with a subject (= a user account).

          What the userinfo endpoint implementation should do next is to collect information about the subject

          (user) from your database. The value of the `subject` is contained in the subject parameter in the

          response from this API and the names of data, i.e., the claims names are contained in the claims

          parameter in the response. For example, if the `subject` parameter is `joe123` and the claims

          parameter is `[ "given_name", "email" ]`, you need to extract information about joe123''s given name

          and email from your database.

          Then, call Authlete''s `/auth/userinfo/issue` API with the collected information and the access token

          in order to make Authlete generate an ID token.

          If an error occurred during the above steps, generate an error response to the client. The response

          should comply with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750). For example, if the

          subject associated with the access token does not exist in your database any longer, you may feel

          like generating a response like below.

          ```

          HTTP/1.1 400 Bad Request

          WWW-Authenticate: Bearer error="invalid_token",

          error_description="The subject associated with the access token does not exist."

          Cache-Control: no-store

          Pragma: no-cache

          ```

          Also, an error might occur on database access. If you treat the error as an internal server error,

          then the response would be like the following.

          ```

          HTTP/1.1 500 Internal Server Error

          WWW-Authenticate: Bearer error="server_error",

          error_description="Failed to extract information about the subject from the database."

          Cache-Control: no-store

          Pragma: no-cache

          ```

          </Accordion>

          '
      parameters:
      - in: path
        name: serviceId
        description: A service ID.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userinfo_request'
            example:
              token: Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/userinfo_request'
      responses:
        '200':
          description: User info retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userinfo_response'
              example:
                resultCode: A091001
                resultMessage: '[A091001] The access token presented at the userinfo endpoint is valid.'
                action: OK
                clientId: '15518267821'
                clientIdAliasUsed: false
                scopes:
                - openid
                subject: john
                token: Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: auth_userinfo_api
      x-code-samples:
      - lang: shell
        label: curl
        source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/userinfo \

          -H ''Content-Type:application/json'' \

          -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \

          -d ''{ "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI" }''

          '
      - lang: java
        label: java
        source: 'AuthleteConfiguration conf = ...;

          AuthleteApi api = AuthleteApiFactory.create(conf);


          UserInfoRequest req = new UserInfoRequest();

          req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI");


          api.userinfo(req);

          '
      - lang: python
        source: 'conf = ...

          api = AuthleteApiImpl(conf)


          req = UserInfoRequest()

          req.token = ''Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI''


          api.userinfo(req)

          '
      tags:
      - UserInfo Endpoint
  /api/{serviceId}/auth/userinfo/issue:
    post:
      summary: Issue UserInfo Response
      description: 'This API generates an ID token.

        '
      x-mint:
        metadata:
          description: This API generates an ID token.
        content: '<Accordion title="Full description" defaultOpen={false}>

          This API is supposed to be called from within the implementation of the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)

          of the authorization server in order to generate an ID token. Before calling this API, a valid

          response from `/auth/userinfo` API must be obtained. Then, call this API with the access token

          contained in the response and the claims values of the user (subject) associated with the access

          token. See **OK** written in the description of `/auth/userinfo` API for details.

          The response from `/auth/userinfo/issue` API has various parameters. Among them, it is `action`

          parameter that the authorization server implementation should check first because it denotes the

          next action that the authorization server implementation should take. According to the value of

          `action`, the service implementation must take the steps described below.


          ## INTERNAL_SERVER_ERROR


          When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization

          server implementation was wrong or that an error occurred in Authlete. In either case, from the

          viewpoint of the client application, it is an error on the server side. Therefore, the service

          implementation should generate a response to the client application with HTTP status of "500 Internal

          Server Error".

          The parameter `responseContent` returns a string which describes the error in the format of [RFC

          6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo

          endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`

          header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 500 Internal Server Error

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## BAD_REQUEST


          When the value of `action` is `BAD_REQUEST`, it means that the request from the client application

          does not contain an access token (= the request from the authorization server implementation to

          Authlete does not contain `token` parameter).

          The parameter `responseContent` returns a string which describes the error in the format of [RFC

          6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo

          endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`

          header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 400 Bad Request

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## UNAUTHORIZED


          When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist, has

          expired, or is not associated with any subject (= any user account).

          The parameter `responseContent` returns a string which describes the error in the format of [RFC

          6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo

          endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`

          header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 401 Unauthorized

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## FORBIDDEN


          When the value of `action` is `FORBIDDEN`, it means that the access token does not include the

          `openid` scope.

          The parameter `responseContent` returns a string which describes the error in the format of [RFC

          6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage) so the userinfo

          endpoint implementation can use the value of `responseContent` as the value of`WWW-Authenticate`

          header.

          The following is an example response which complies with RFC 6750. Note that OpenID Connect Core

          1.0 requires that an error response from userinfo endpoint comply with RFC 6750. See [5.3.3. UserInfo

          Response](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoError) for details.

          ```

          HTTP/1.1 403 Forbidden

          WWW-Authenticate: &#123;responseContent&#125;

          Cache-Control: no-store

          Pragma: no-cache

          ```


          ## JSON


          When the value of `action` is `JSON`, it means that the access token which the client application

          presented is valid and an ID token was successfully generated in the format of JSON.

          The userinfo endpoint implementation is expected to generate a response to the client application.

          The content type of the response must be `application/json` and the response body must be an ID

          token in JSON format.

          The value of `responseContent` is the ID token in JSON format when `action` is `JSON`, so

          a response to the client can be built like below.

          ```

          HTTP/1.1 200 OK

          Cache-Control: no-store

          Pragma: no-cache

          Content-Type: application/json;charset=UTF-8

          &#123;responseContent&#125;

          ```


          ## JWT


          When the value of `action` is `JWT`, it means that the access token which the client application

          presented is valid and an ID token was successfully generated in the format of JWT (JSON Web Token)

          ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)).

          The userinfo endpoint implementation is expected to generate a response to the client application.

          The content type of the response must be `application/jwt` and the response body must be an ID

          token in JWT format.

          The value of `responseContent` is the ID token in JSON format when `action` is `JWT`, so a response

          to the client can be built like below.

          ```

          HTTP/1.1 200 OK

          Cache-Control: no-store

          Pragma: no-cache

          Content-Type: application/jwt

          &#123;responseContent&#125;

          ```

          </Accordion>

          '
      parameters:
      - in: path
        name: serviceId
        description: A service ID.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userinfo_issue_request'
            example:
              token: Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/userinfo_issue_request'
      responses:
        '200':
          description: User info issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userinfo_issue_response'
              example:
                resultCode: A096001
                resultMessage: '[A096001] An ID token was generated successfully.'
                action: JSON
                responseContent: '{\"exp\":1511600971,\"sub\":\"john\",\"aud\":[\"26478243745571\"],\"iss\":\"https://authlete.com\",\"iat\":1511514571}'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      operationId: auth_userinfo_issue_api
      x-code-samples:
      - lang: shell
        label: curl
        source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/userinfo/issue \

          -H ''Content-Type:application/json'' \

          -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \

          -d ''{ "token": "Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI" }''

          '
      - lang: java
        label: java
        source: 'AuthleteConfiguration conf = ...;

          AuthleteApi api = AuthleteApiFactory.create(conf);


          UserInfoIssueRequest req = new UserInfoIssueRequest();

          req.setToken("Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI");


          api.userinfoIssue(req);

          '
      - lang: python
        source: 'conf = ...

          api = AuthleteApiImpl(conf)


          req = UserInfoIssueRequest()

          req.token = ''Ntm9MDb8WXQAevqrBkd84KTTHbYHVQrTjgUZCOWqEUI''


          api.userinfoIssue(req)

          '
      tags:
      - UserInfo Endpoint
components:
  responses:
    '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.'
    '403':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001215
            resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.'
  schemas:
    userinfo_issue_request:
      type: object
      required:
      - token
      properties:
        token:
          type: string
          description: 'The access token that has been passed to the userinfo endpoint by the client application. In other words,

            the access token which was contained in the userinfo request.

            '
        claims:
          type: string
          description: 'Claims in JSON format. As for the format, see [OpenID Connect Core 1.0, 5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).

            '
        sub:
          type: string
          description: 'The value of the `sub` claim. If the value of this request parameter is not empty, it is used as the value of

            the `sub` claim. Otherwise, the value of the subject associated with the access token is used.

            '
        claimsForTx:
          type: string
          description: 'Claim key-value pairs that are used to compute transformed claims.

            '
        requestSignature:
          type: string
          description: 'The Signature header value from the request.

            '
        headers:
          type: array
          items:
            $ref: '#/components/schemas/pair'
          description: 'HTTP headers to be included in processing the signature. If this is a signed request, this must include the

            Signature and Signature-Input headers, as well as any additional headers covered by the signature.

            '
        verifiedClaimsForTx:
          type: array
          items:
            type: string
          description: 'Values of verified claims requested indirectly by "transformed claims".

            '
          x-mint:
            metadata:
              description: Values of verified claims requested indirectly by "transformed claims".
            content: "<Accordion title=\"Full description\" defaultOpen={false}>\nA client application may request \"transformed claims\". Each of transformed claims uses an existing\nclaim as input. As a result, to compute the value of a transformed claim, the value of the referenced\nexisting claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide\nvalues of existing claims for computation of transformed claims.\n\nA response from the `/auth/userinfo` API may include the `requestedVerifiedClaimsForTx` response\nparameter which is a list of verified claims that are referenced indirectly by transformed claims\n(cf. `requestedVerifiedClaimsForTx` in `/auth/userinfo` API response). The authorization server\nimplementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx`\nand pass them as the value of this `verifiedClaimsForTx` request parameter.\n\nThe following is an example of the value of this request parameter.\n\n```\n[\n  \"&#123;\\\"birthdate\\\":\\\"1970-01-23\\\",\\\"nationalities\\\":[\\\"DEU\\\",\\\"USA\\\"]&#125;\"\n]\n```\n\nThe reason that this `verifiedClaimsForTx` property is an array is that the `\"verified_claims\"`\nproperty in the claims request parameter of an authorization request can be an array like below.\n\n```\n&#123;\n  \"transformed_claims\": &#123;\n    \"nationality_usa\": &#123;\n      \"claim\": \"nationalities\",\n      \"fn\": [\n        [ \"eq\", \"USA\" ],\n        \"any\"\n      ]\n    &#125;\n  &#125;,\n  \"userinfo\": &#123;\n    \"verified_claims\": [\n      &#123;\n        \"verification\": &#123; \"trust_framework\": &#123; \"value\": \"gold\" &#125; &#125;,\n        \"claims\": &#123; \"::18_or_above\": null &#125;\n      &#125;,\n      &#123;\n        \"verification\": &#123; \"trust_framework\": &#123; \"value\": \"silver\" &#125; &#125;,\n        \"claims\": &#123; \":nationality_usa\": null &#125;\n      &#125;\n    ]\n  &#125;\n&#125;\n```\n\nFor the example above, the value of this `verifiedClaimsForTx` property should be an array of\nsize 2 and look like below. The first element is JSON including claims which have been verified\nunder the trust framework `\"gold\"`, and the second element is JSON including claims which have\nbeen verified under the trust framework `\"silver\"`.\n\n```\n[\n  \"&#123;\\\"birthdate\\\":\\\"1970-01-23\\\"&#125;\",\n  \"&#123;\\\"nationalities\\\":[\\\"DEU\\\",\\\"USA\\\"]&#125;\"\n]\n```\n</Accordion>\n"
    userinfo_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
          - FORBIDDEN
          - OK
          description: The next action that the authorization server implementation should take.
        claims:
          type: array
          items:
            type: string
          description: 'The list of claims that the client application requests to be embedded in the ID token.

            '
        clientId:
          type: integer
          format: int64
          description: 'The ID of the client application which is associated with the access token.

            '
        clientIdAlias:
          type: string
          description: 'The client ID alias when the authorization request for the access token was made.

            '
        clientIdAliasUsed:
          type: boolean
          description: 'The flag which indicates whether the client ID alias was used when the authorization

            request for the access token was made.

            '
        responseContent:
          type: string
          description: 'The content that the authorization server implementation can use as the value of `WWW-Authenticate`

            header on errors.

            '
        scopes:
          type: array
          items:
            type: string
          description: 'The scopes covered by the access token.

            '
        subject:
          type: string
          description: 'The subject (= resource owner''s ID).

            '
        token:
          type: string
          description: 'The access token that came along with the userinfo request.

            '
        properties:
          type: array
          items:
            $ref: '#/components/schemas/property'
          description: 'The extra properties associated with the access token.

            '
        userInfoClaims:
          type: string
          description: 'The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object.

            '
          x-mint:
            metadata:
              description: The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in an authorization request object.
            content: "<Accordion title=\"Full description\" defaultOpen={false}>\nA client application may request certain claims be embedded in an ID token or in a response from the userInfo endpoint.\nThere are several ways. Including the `claims` request parameter and including the `claims` property in a request object are such examples.\nIn both cases, the value of the `claims` parameter/property is JSON. Its format is described in [5.5. Requesting Claims using the \"claims\"\nRequest Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).\n\nThe following is an excerpt from the specification. You can find `userinfo` and `id_token` are top-level properties.\n\n```json\n&#123;\n  \"userinfo\":\n  &#123;\n    \"given_name\": &#123; \"essential\": true &#125;,\n    \"nickname\": null,\n    \"email\": &#123; \"essential\": true &#125;,\n    \"email_verified\": &#123; \"essential\": true &#125;,\n    \"picture\": null,\n    \"http://example.info/claims/groups\": null\n  &#125;,\n  \"id_token\":\n  &#123;\n    \"auth_time\": &#123; \"essential\": true &#125;,\n    \"acr\": &#123; \"values\": [ \"urn:mace:incommon:iap:silver\" ] &#125;\n  &#125;\n&#125;\n````\n\nThe value of this property is the value of the `userinfo` property in JSON format.\nFor example, if the JSON above is included in an authorization request, this property holds JSON equivalent to the following.\n\n```json\n&#123;\n  \"given_name\": &#123; \"essential\": true &#125;,\n  \"nickname\": null,\n  \"email\": &#123; \"essential\": true &#125;,\n  \"email_verified\": &#123; \"essential\": true &#125;,\n  \"picture\": null,\n  \"http://example.info/claims/groups\": null\n&#125;\n```\n\nNote that if a request object is given and it contains the `claims` property and if the `claims` request parameter is also given,\nthe value of this property holds the former value.\n</Accordion>\n"
        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.

            '
        consentedClaims:
          type: array
          items:
            type: string
          description: 'the claims that the user has consented for the client application

            to know.

            '
        requestedClaimsForTx:
          type: array
          items:
            type: string
          description: 'Get names of claims that are requested indirectly by *"transformed

            claims"*.

            A client application can request *"transformed claims"* by adding

            names of transformed claims in the `claims` request parameter.

            The following is an example of the `claims` request parameter

            that requests a predefined transformed claim named `18_or_over`

            and a transformed claim named `nationality_usa` to be embedded

            in the response from the userinfo endpoint.

            ```json

            &#123;

            "transformed_claims": &#123;

            "nationality_usa": &#123;

            "claim": "nationalities",

            "fn": [

            [ "eq", "USA" ],

            "any"

            ]

            &#125;

            &#125;,

            "userinfo": &#123;

            "::18_or_over": null,

            ":nationality_usa": null

            &#125;

            &#125;

            ```

            The example above assumes that a transformed claim named `18_or_over`

            is predefined by the authorization server like below.

            ```json

            &#123;

            "18_or_over": &#123;

            "claim": "birthdate",

            "fn": [

            "years_ago",

            [ "gte", 18 ]

            ]

            &#125;

            &#125;

            ```

            In the example, the `nationalities` claim is requested indirectly

            by the `nationality_usa` transformed claim. Likewise, the

            `birthdate` claim is requested indirectly by the `18_or_over`

            transformed claim.

            When the `claims` request parameter of an authorization request is

            like the example above, this `requestedClaimsForTx` property will

            hold the following value.

            ```json

            [ "birthdate", "nationalities" ]

            ```

            It is expected that the authorization server implementation prepares values

            of the listed claims and passes them as the value of the `claimsForTx`

            request parameter when it calls the `/api/auth/userinfo/issue` API. The following

            is an example of the value of the `claimsForTx` request parameter.

            ```json

            &#123;

            "birthdate": "1970-01-23",

            "nationalities": [ "DEU", "USA" ]

            &#125;

            ```

            '
        requestedVerifiedClaimsForTx:
          type: array
          items:
            type: array
            items:
              type: string
          description: 'Names of verified claims that will be referenced when transformed claims are computed.

            '
        transformedClaims:
          type: string
          description: 'the value of the `transformed_claims` property in the `claims` request

            parameter of an authorization request or in the `claims` property in a

            request object.

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

            '
        dpopNonce:
          type: string
          description: 'The expected nonce value for DPoP proof JWT, which should be used

            as the value of the `DPoP-Nonce` HTTP header.

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

            '
    pair:
      type: object
      properties:
        key:
          type: string
          description: The key part.
        value:
          type: string
          description: The value part.
    userinfo_issue_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
          - FORBIDDEN
          - JSON
          - JWT
          description: The next action that the authorization server implementation should take.
        responseContent:
          type: string
          description: 'The content that the authorization server implementation can use as the value of `WWW-Authenticate`

            header on errors.

            '
        signature:
          type: string
          description: 'The signature header of the response message.

            '
        signatureInput:
          type: string
          description: 'The signature-input header of the response message

            '
        contentDigest:
          type: string
          description: 'The content-digest header of the response message

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

            '
    userinfo_request:
      type: object
      required:
      - token
      properties:
        token:
          type: string
          description: 'An access token.

            '
        clientCertificate:
          type: string
          description: 'Client certificate used in the TLS connection established between the client application and the userinfo endpoint.


            The value of this request parameter is referred to when the access token given to the userinfo endpoint was bound to

            a client certificate when it was issued. See [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens]

            (https://datatracker.ietf.org/doc/rfc8705/) for details about the specification of certificate-bound access tokens.

            '
        dpop:
          type: string
          description: '`DPoP` header presented by the client during the request to the user info endpoint.


            The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT.

            See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop)

            for details.

            '
        htm:
          type: string
          description: 'HTTP method of the user info request. This field is used to validate the DPoP header.

            In normal cases, the value is either `GET` or `POST`.

            '
        htu:
          type: string
          description: 'URL of the user info endpoint. This field is used to validate the DPoP header.


            If this parameter is omitted, the `userInfoEndpoint` property of the service is used as the default value.

            See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop)

            for details.

            '
        uri:
          type: string
          description: 'The full URL of the userinfo endpoint.

            '
        message:
          type: string
          description: 'The HTTP message body of the request, if present.

            '
        headers:
          type: array
          items:
            $ref: '#/components/schemas/pair'
          description: 'HTTP headers to be included in processing the signature. If this is a signed request, this must include the

            Signature and Signature-Input headers, as well as any additional headers covered by the signature.

            '
        targetUri:
          type: string
          description: 'The target URI of the userinfo request, including the query part, if any.

            '
          x-mint:
            metadata:
              description: The target URI of the userinfo request, including the query part, if any.
            content: '<Accordion title="Full description" defaultOpen={false}>

              This parameter is used as the value of the `@target-uri` derived component for HTTP message signatures

              ([RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)).

              Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and

              `@query-param` are computed from this parameter.


              When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter

              represents the URL of the userinfo endpoint, which usually serves as the target URI of the userinfo request.

              The only exception is when the access token is specified as a query parameter, as defined in

              [RFC 6750 Section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3). However, RFC 6750

              states that this method "SHOULD NOT be used" unless other methods are not viable.


              If neither this `targetUri` parameter nor the `htu` parameter is specified, the `userInfoEndpoint`

              property of the service is used as a fallback.

              </Accordion>

              '
        dpopNonceRequired:
          type: boolean
          description: 'The flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value.


            If this request parameter is set to `true` or if the service''s `dpopNonceRequired` property is

            set to `true`, the `/auth/userinfo` API checks if the DPoP proof JWT includes the expected `nonce`

            value. In this case, the response from the `/auth/userinfo` API will include the `dpopNonce` response

            parameter, which should be used as the value of the DPoP-Nonce HTTP header.

            '
        requestBodyContained:
          type: boolean
          description: 'The flag indicating whether the userinfo request contains a request body.

            '
          x-mint:
            metadata:
              description: The flag indicating whether the userinfo request contains a request body.
            content: '<Accordion title="Full description" defaultOpen={false}>

              When the userinfo request must comply with the HTTP message signing requirements defined in the

              FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included

              in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html))

              if the userinfo request contains a request body.


              When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"`

              is included in the signature base, if the FAPI profile applies to the userinfo request.


              NOTE: The FAPI 2.0 Message Signing specification is not applied to the userinfo endpoint until

              its necessity is agreed upon by the industry (cf. [FAPI Issue 723](https://bitbucket.org/openid/fapi/issues/723)).

              </Accordion>

              '
    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.
  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 <token>` 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.

        '