openapi: 3.0.3 info: title: Authlete Authorization 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: Authorization Endpoint description: API endpoints for implementing OAuth 2.0 Authorization Endpoint. x-tag-expanded: false paths: /api/{serviceId}/auth/authorization: post: summary: Process Authorization Request x-badges: - color: red label: Core API description: 'This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. ' x-mint: metadata: description: This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. content: "\nThis API is supposed to be called from within the implementation of the authorization endpoint of\nthe service. The endpoint implementation must extract the request parameters from the authorization\nrequest from the client application and pass them as the value of parameters request parameter for\nAuthlete's `/auth/authorization` API.\nThe value of `parameters` is either (1) the entire query string when the HTTP method of the request\nfrom the client application is `GET` or (2) the entire entity body (which is formatted in\n`application/x-www-form-urlencoded`) when the HTTP method of the request from the client application\nis `POST`.\nThe following code snippet is an example in JAX-RS showing how to extract request parameters from\nthe authorization request.\n```java\n@GET\npublic Response get(@Context UriInfo uriInfo)\n{\n // The query parameters of the authorization request.\n String parameters = uriInfo.getRequestUri().getQuery();\n ......\n}\n@POST\n@Consumes(MediaType.APPLICATION_FORM_URLENCODED)\npublic Response post(String parameters)\n{\n // 'parameters' is the entity body of the authorization request.\n ......\n}\n```\nThe endpoint implementation does not have to parse the request parameters from the client application\nbecause Authlete's `/auth/authorization` API does it.\nThe response from `/auth/authorization` API has various parameters. Among them, it is `action`\nparameter that the authorization server implementation should check first because it denotes the\nnext action that the authorization server implementation should take. According to the value of\n`action`, the service implementation must take the steps described below.\n\n## INTERNAL_SERVER_ERROR\n\nWhen the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization\nserver implementation was wrong or that an error occurred in Authlete.\nIn either case, from the viewpoint of the client application, it is an error on the server side.\nTherefore, the service implementation should generate a response to the client application with\nHTTP status of \"500 Internal Server Error\". Authlete recommends `application/json` as the content\ntype although OAuth 2.0 specification does not mention the format of the error response when the\nredirect URI is not usable.\n\nThe value of `responseContent` is a JSON string which describes the error, so it can be used as\nthe entity body of the response.\n\n---\n\nThe following illustrates the response which the service implementation should generate and return\nto the client application.\n\n```\nHTTP/1.1 500 Internal Server Error\nContent-Type: application/json\nCache-Control: no-store\nPragma: no-cache\n{responseContent}\n```\nThe endpoint implementation may return another different response to the client application\nsince \"500 Internal Server Error\" is not required by OAuth 2.0.\n\n## BAD_REQUEST\n\nWhen the value of `action` is `BAD_REQUEST`, it means that the request from the client application\nis invalid.\nA response with HTTP status of \"400 Bad Request\" should be returned to the client application and\nAuthlete recommends `application/json` as the content type although OAuth 2.0 specification does\nnot mention the format of the error response when the redirect URI is not usable.\n\nThe value of `responseContent` is a JSON string which describes the error, so it can be used as\nthe entity body of the response.\n\n---\n\nThe following illustrates the response which the service implementation should generate and return\nto the client application.\n\n```\nHTTP/1.1 400 Bad Request\nContent-Type: application/json\nCache-Control: no-store\nPragma: no-cache\n{responseContent}\n```\nThe endpoint implementation may return another different response to the client application since\n\"400 Bad Request\" is not required by OAuth 2.0.\n\n## LOCATION\n\nWhen the value of `action` is `LOCATION`, it means that the request from the client application\nis invalid but the redirect URI\nto which the error should be reported has been determined.\nA response with HTTP status of \"302 Found\" must be returned to the client application with `Location`\nheader which has a redirect URI with error parameter.\n\nThe value of `responseContent` is a redirect URI with `error` parameter, so it can be used as the\nvalue of `Location` header.\n\nThe following illustrates the response which the service implementation must generate and return\nto the client application.\n\n```\nHTTP/1.1 302 Found\nLocation: {responseContent}\nCache-Control: no-store\nPragma: no-cache\n```\n\n## FORM\n\nWhen the value of `action` is `FORM`, it means that the request from the client application is\ninvalid but the redirect URI to which the error should be reported has been determined, and that\nthe authorization request contains `response_mode=form_post` as is defined in [OAuth 2.0 Form Post\nResponse Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html).\nThe HTTP status of the response returned to the client application should be \"200 OK\" and the\ncontent type should be `text/html;charset=UTF-8`.\n\nThe value of `responseContent` is an HTML which can be used as the entity body of the response.\n\n---\n\nThe following illustrates the response which the service implementation must generate and return\nto the client application.\n\n```\nHTTP/1.1 200 OK\nContent-Type: text/html;charset=UTF-8\nCache-Control: no-store\nPragma: no-cache\n{responseContent}\n```\n\n## NO_INTERACTION\n\nWhen the value of `action` is `NO_INTERACTION`, it means that the request from the client application\nhas no problem and requires the service to process the request without displaying any user interface\npages for authentication or consent. This case happens when the authorization request contains\n`prompt=none`.\nThe service must follow the steps described below.\n\n**[1] END-USER AUTHENTICATION**\n\nCheck whether an end-user has already logged in. If an end-user has logged in, go to the next step ([MAX_AGE]).\nOtherwise, call Authlete's `/auth/authorization/fail` API with `reason=NOT_LOGGED_IN` and use the response from\nthe API to generate a response to the client application.\n\n**[2] MAX AGE**\n\nGet the value of `maxAge` parameter from the `/auth/authorization` API response. The value represents\nthe maximum authentication age which has come from `max_age` request parameter or `defaultMaxAge`\nconfiguration parameter of the client application. If the value is `0`, go to the next step ([SUBJECT]).\nOtherwise, follow the sub steps described below.\n\n- (i) Get the time at which the end-user was authenticated. Note that this value is not managed by Authlete,\n meaning that it is expected that the service implementation manages the value. If the service implementation\n does not manage authentication time of end-users, call Authlete's `/auth/authorization/fail` API\n with `reason=MAX_AGE_NOT_SUPPORTED` and use the API response to generate a response to the client\n application.\n- (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication\n time. The calculated value is the expiration time.\n- (iii) Check whether the calculated value is equal to or greater than the current time. If this condition\n is satisfied, go to the next step ([SUBJECT]). Otherwise, call Authlete's `/auth/authorization/fail`\n API with `reason=EXCEEDS_MAX_AGE` and use the API response to generate a response to the client\n application.\n\n**[3] SUBJECT**\n\nGet the value of `subject` from the `/auth/authorization` API response. The value represents an\nend-user who the client application expects to grant authorization. If the value is `null`, go to\nthe next step ([ACRs]). Otherwise, follow the sub steps described below.\n\n- (i) Compare the value of the requested subject to the current end-user.\n- (ii) If they are equal, go to the next step ([ACRs]). If they are not equal, call Authlete's\n `/auth/authorization/fail` API with `reason=DIFFERENT_SUBJECT` and use the response from the API\n to generate a response to the client application.\n\n**[4] ACRs**\n\nGet the value of `acrs` from the `/auth/authorization` API response. The value represents a list\nof ACRs (Authentication Context Class References) and comes from (1) acr claim in `claims` request\nparameter, (2) `acr_values` request parameter, or (3) `default_acr_values` configuration parameter\nof the client application.\nIt is ensured that all the ACRs in acrs are supported by the authorization server implementation.\nIn other words, it is ensured that all the ACRs are listed in `acr_values_supported` configuration\nparameter of the authorization server.\nIf the value of ACRs is `null`, go to the next step ([ISSUE]). Otherwise, follow the sub steps\ndescribed below.\n\n- (i) Get the ACR performed for the authentication of the current end-user. Note that this value is\n managed not by Authlete but by the authorization server implementation. (If the authorization server\n implementation cannot handle ACRs, it should not have listed ACRs as `acr_values_supported`.)\n- (ii) Compare the ACR value obtained in the above step to each element in the ACR array (`acrs`)\n in the listed order.\n- (iii) If the ACR value was found in the array, (= the ACR performed for the authentication of the\n current end-user did not match any one of the ACRs requested by the client application), check\n whether one of the requested ACRs must be satisfied or not using `acrEssential` parameter in the\n `/auth/authorization` API response. If the value of `acrEssential` parameter is `true`, call Authlete's\n `/auth/authorization/fail` API with `reason=ACR_NOT_SATISFIED` and use the response from the API\n to generate a response to the client application. Otherwise, go to the next step ([SCOPES]).\n\n**[5] SCOPES**\n\nGet the value of `scopes` from the `/auth/authorization` API response. If the array contains a\nscope which has not been granted to the client application by the end-user in the past, call\nAuthlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from\nthe API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).\nNote that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`\nAPIs), which is only available in a dedicated/onpremise Authlete server (contact sales@authlete.com\nfor details).\n\n**[6] DYNAMIC SCOPES**\n\nGet the value of `dynamicScopes` from the `/auth/authorization` API response. If the array contains\na scope which has not been granted to the client application by the end-user in the past, call\nAuthlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from\nthe API to generate a response to the client application. Otherwise, go to the next step ([RESOURCES]).\nNote that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`\nAPIs) but dynamic scopes are not remembered as granted scopes.\n\n**[7] RESOURCES**\n\nGet the value of `resources` from the `/auth/authorization` API response. The array represents\nthe values of the `resource` request parameters. If you want to reject the request, call Authlete's\n`/auth/authorization/fail` API with `reason=INVALID_TARGET` and use the response from the API to\ngenerate a response to the client application. Otherwise, go to the next step ([ISSUE]).\nSee \"Resource Indicators for OAuth 2.0\" for details.\n\n**[8] ISSUE**\n\nIf all the above steps succeeded, the last step is to issue an authorization code, an ID token\nand/or an access token. (There is a special case, though. In the case of `response_type=none`,\nnothing is issued.) It can be performed by calling Authlete's `/auth/authorization/issue` API.\nThe API requires the following parameters. Prepare these parameters and call `/auth/authorization/issue`\nAPI and use the response to generate a response to the client application.\n- `ticket` (required)\n This parameter represents a ticket which is exchanged with tokens at `/auth/authorization/issue`.\n Use the value of `ticket` contained in the `/auth/authorization` API response.\n- `subject` (required)\n This parameter represents the unique identifier of the current end-user. It is often called \"user ID\"\n and it may or may not be visible to the user. In any case, it is a number or a string assigned\n to an end-user by the authorization server implementation. Authlete does not care about the format\n of the value of subject, but it must consist of only ASCII letters and its length must not exceed 100.\n When the value of `subject` parameter in the /auth/authorization API response is not `null`,\n it is necessarily identical to the value of `subject` parameter in the `/auth/authorization/issue`\n API request.\n The value of this parameter will be embedded in an ID token as the value of `sub` claim. When\nthe value of `subject_type` configuration parameter of the client application is `PAIRWISE`,\n the value of sub claim is different from the value specified by this parameter, See [8. Subject\nIdentifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) of OpenID\n Connect Core 1.0 for details about subject types.\n You can use the `sub` request parameter to adjust the value of the `sub` claim in an ID token.\n See the description of the `sub` request parameter for details.\n- `authTime` (optional)\n This parameter represents the time when the end-user authentication occurred. Its value is the\n number of seconds from `1970-01-01`. The value of this parameter will be embedded in an ID token\nas the value of `auth_time` claim.\n- `acr` (optional)\n This parameter represents the ACR (Authentication Context Class Reference) which the authentication\n of the end-user satisfies. When `acrs` in the `/auth/authorization` API response is a non-empty\n array and the value of `acrEssential` is `true`, the value of this parameter must be one of the\n array elements. Otherwise, even `null` is allowed. The value of this parameter will be embedded\n in an ID token as the value of `acr` claim.\n- `claims` (optional)\n This parameter represents claims of the end-user. \"Claims\" here are pieces of information about\n the end-user such as `\"name\"`, `\"email\"` and `\"birthdate\"`. The authorization server implementation\n is required to gather claims of the end-user, format the claim values into JSON and set the JSON\n string as the value of this parameter.\n The claims which the authorization server implementation is required to gather are listed in\n `claims` parameter in the `/auth/authorization` API response.\n For example, if claims parameter lists `\"name\"`, `\"email\"` and `\"birthdate\"`, the value of this\n parameter should look like the following.\n ```json\n {\n \"name\": \"John Smith\",\n \"email\": \"john@example.com\",\n \"birthdate\": \"1974-05-06\"\n }\n ```\n `claimsLocales` parameter in the `/auth/authorization` API response lists the end-user's preferred\n languages and scripts, ordered by preference. When `claimsLocales` parameter is a non-empty array,\n its elements should be taken into account when the authorization server implementation gathers\nclaim values. Especially, note the excerpt below from [5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)\n of OpenID Connect Core 1.0.\n> When the OP determines, either through the `claims_locales` parameter, or by other means, that\n the End-User and Client are requesting Claims in only one set of languages and scripts, it is\n RECOMMENDED that OPs return Claims without language tags when they employ this language and script.\n It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims\n using language tags.\n If `claims` parameter in the `/auth/authorization` API response is `null` or an empty array,\n the value of this parameter should be `null`.\nSee [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)\n of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the authorization\nserver implementation support its special claims ([5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims))\nand (2) that claim names may be followed by a language tag ([5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)).\nRead the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)\n for details.\n The claim values in this parameter will be embedded in an ID token.\n Note that `idTokenClaims` parameter is available in the `/auth/authorization` API response.\nThe parameter has the value of the `\"id_token\"` property in the `claims` request parameter or\n in the `\"claims\"` property in a request object. The value of this parameter should be considered\n when you prepare claim values.\n- `properties` (optional)\n Extra properties to associate with an access token and/or an authorization code that may be issued\n by this request. Note that `properties` parameter is accepted only when `Content-Type` of the\n request is `application/json`, so don't use `application/x-www-form-urlencoded` for details.\n- `scopes` (optional)\n Scopes to associate with an access token and/or an authorization code. If this parameter is `null`,\n the scopes specified in the original authorization request from the client application are used.\n In other cases, including the case of an empty array, the specified scopes will replace the original\n scopes contained in the original authorization request.\n Even scopes that are not included in the original authorization request can be specified. However,\n as an exception, `openid` scope is ignored on the server side if it is not included in the original\n request. It is because the existence of `openid` scope considerably changes the validation steps\n and because adding `openid` triggers generation of an ID token (although the client application\n has not requested it) and the behavior is a major violation against the specification.\nIf you add `offline_access` scope although it is not included in the original request, keep in\n mind that the specification requires explicit consent from the user for the scope ([OpenID Connect\nCore 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)).\nWhen `offline_access` is included in the original request, the current implementation of Authlete's\n `/auth/authorization` API checks whether the request has come along with `prompt` request parameter\n and the value includes consent. However, note that the implementation of Authlete's `/auth/authorization/issue`\nAPI does not perform such checking if `offline_access` scope is added via this `scopes` parameter.\n- `sub` (optional)\n The value of the `sub` claim in an ID token. If the value of this request parameter is not empty,\n it is used as the value of the `sub` claim. Otherwise, the value of the `subject` request parameter\n is used as the value of the `sub` claim. The main purpose of this parameter is to hide the actual\n value of the subject from client applications.\n Note that even if this `sub` parameter is not empty, the value of the subject request parameter\n is used as the value of the subject which is associated with the access token.\n\n## INTERACTION\n\nWhen the value of `action` is `INTERACTION`, it means that the request from the client application\nhas no problem and requires the service to process the request with user interaction by an HTML form.\nThe purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to\nthe client application. The items described below are some points which the service implementation\nshould take into account when it builds the UI.\n\n**[1] DISPLAY MODE**\n\nThe response from `/auth/authorization` API has `display` parameter. It is one of `PAGE` (default),\n`POPUP`, `TOUCH` and `WAP` The meanings of the values are described in [3.1.2.1. Authentication\nRequest of OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).\nBasically, the authorization server implementation should display the UI which is suitable for the\ndisplay mode, but it is okay for the authorization server implementation to \"attempt to detect the\ncapabilities of the User Agent and present an appropriate display\".\nIt is ensured that the value of `display` is one of the supported display modes which are specified\nby `supportedDisplays` configuration parameter of the service.\n\n**[2] UI LOCALE**\n\nThe response from `/auth/authorization` API has `uiLocales` parameter. It it is not `null`, it lists\nlanguage tag values (such as `fr-CA`, `ja-JP` and `en`) ordered by preference. The service implementation\nshould display the UI in one of the language listed in the parameter when possible. It is ensured\nthat language tags listed in `uiLocales` are contained in the list of supported UI locales which\nare specified by `supportedUiLocales` configuration parameter of the service.\n\n**[3] CLIENT INFORMATION**\n\nThe authorization server implementation should show information about the client application to\nthe end-user. The information is embedded in `client` parameter in the response from `/auth/authorization`\nAPI.\n\n**[4] SCOPES**\n\nA client application requires authorization for specific permissions. In OAuth 2.0 specification,\n\"scope\" is a technical term which represents a permission. `scopes` parameter in the response\nfrom `/auth/authorization` API is a list of scopes requested by the client application. The service\nimplementation should show the end-user the scopes.\nThe authorization server implementation may choose not to show scopes to which the end-user has\ngiven consent in the past. To put it the other way around, the authorization server implementation\nmay show only the scopes to which the end-user has not given consent yet. However, if the value\nof `prompts` response parameter contains `CONSENT`, the authorization server implementation has\nto obtain explicit consent from the end-user even if the end-user has given consent to all the\nrequested scopes in the past.\nNote that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`\nAPIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server\n(contact sales@authlete.com for details). In other words, the APIs of the shared Authlete server\nare disabled intentionally (in order to prevent garbage data from being accumulated) and they\nreturn 403 Forbidden.\nIt is ensured that the values in `scopes` parameter are contained in the list of supported scopes\nwhich are specified by `supportedScopes` configuration parameter of the service.\n\n**[5] DYNAMIC SCOPES**\n\nThe authorization request may include dynamic scopes. The list of recognized dynamic scopes are\naccessible by getDynamicScopes() method. See the description of the [DynamicScope](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html)\nclass for details about dynamic scopes.\n\n**[6] AUTHORIZATION DETAILS**\n\nThe authorization server implementation should show the end-user \"authorization details\" if the\nrequest includes it. The value of `authorization_details` parameter in the response is the content\nof the `authorization_details` request parameter.\nSee \"OAuth 2.0 Rich Authorization Requests\" for details.\n\n**[7] PURPOSE**\n\nThe authorization server implementation must show the value of the `purpose` request parameter if\nit supports [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html).\nSee [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8)\nin the specification for details.\nNote that the value of `purpose` response parameter is the value of the purpose request parameter.\n\n**[7] END-USER AUTHENTICATION**\n\nNecessarily, the end-user must be authenticated (= must login the service) before granting authorization\nto the client application. Simply put, a login form is expected to be displayed for end-user authentication.\nThe service implementation must follow the steps described below to comply with OpenID Connect.\n(Or just always show a login form if it's too much of a bother.)\n\n- (i) Get the value of `prompts` response parameter. It corresponds to the value of the `prompt`\n request parameter. Details of the request parameter are described in [3.1.2.1. Authentication\n Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of OpenID Connect Core 1.0.\n- (ii) If the value of `prompts` parameter is `SELECT_ACCOUNT` display a form to let the end-user\n select on of his/her accounts for login. If `subject` response parameter is not `null`, it is the\n end-user ID that the client application expects, so the value should be used to determine the value\n of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of\n `subject` response parameter is `null`, the value of `loginHint` response parameter should be referred\n to as a hint to determine the value of the login ID. The value of `loginHint` response parameter\n is simply the value of the `login_hint` request parameter.\n- (iii) If the value of `prompts` response parameter contains `LOGIN`, display a form to urge the\n end-user to login even if the end-user has already logged in. If the value of `subject` response\n parameter is not `null`, it is the end-user ID that the client application expects, so the value\n should be used to determine the value of the login ID. Note that a subject and a login ID are not\n necessarily equal. If the value of `subject` response parameter is `null`, the value of `loginHint`\n response parameter should be referred to as a hint to determine the value of the login ID. The value\n of `loginHint` response parameter is simply the value of the `login_hint` request parameter.\n- (iv) If the value of `prompts` response parameter does not contain `LOGIN`, the authorization server\n implementation does not have to authenticate the end-user if all the conditions described below\n are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate\n the end-user.\n - An end-user has already logged in the service.\n - The login ID of the current end-user matches the value of `subject` response parameter.\n This check is required only when the value of `subject` response parameter is a non-null value.\n - The max age, which is the number of seconds contained in `maxAge` response parameter,\n has not passed since the current end-user logged in your service. This check is required only when\n the value of `maxAge` response parameter is a non-zero value.\n - If the authorization server implementation does not manage authentication time of end-users\n (= if the authorization server implementation cannot know when end-users logged in) and if the\n value of `maxAge` response parameter is a non-zero value, a login form should be displayed.\n - The ACR (Authentication Context Class Reference) of the authentication performed for\n the current end-user satisfies one of the ACRs listed in `acrs` response parameter. This check is\n required only when the value of `acrs` response parameter is a non-empty array.\n In every case, the end-user authentication must satisfy one of the ACRs listed in `acrs` response\n parameter when the value of `acrs` response parameter is a non-empty array and `acrEssential`\n response parameter is `true`.\n\n**[9] GRANT/DENY BUTTONS**\n\nThe end-user is supposed to choose either (1) to grant authorization to the client application or\n(2) to deny the authorization request. The UI must have UI components to accept the judgment by\nthe user. Usually, a button to grant authorization and a button to deny the request are provided.\nWhen the value of `subject` response parameter is not `null`, the end-user authentication must be\nperformed for the subject, meaning that the authorization server implementation should repeatedly\nshow a login form until the subject is successfully authenticated.\nThe end-user will choose either (1) to grant authorization to the client application or (2) to\ndeny the authorization request. When the end-user chose to deny the authorization request, call\nAuthlete's `/auth/authorization/fail` API with `reason=DENIED` and use the response from the API\nto generate a response to the client application.\nWhen the end-user chose to grant authorization to the client application, the authorization server\nimplementation has to issue an authorization code, an ID token, and/or an access token to the client\napplication. (There is a special case. When `response_type=none`, nothing is issued.) Issuing the\ntokens can be performed by calling Authlete's `/auth/authorization/issue` API. Read [ISSUE] written\nabove in the description for the case of `action=NO_INTERACTION`.\n\n" parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_request' example: parameters: response_type=code&client_id=26478243745571&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&scope=timeline.read+history.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256 application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_request' responses: '200': description: Authorization request processed successfully content: application/json: schema: $ref: '#/components/schemas/authorization_response' example: resultCode: A004001 resultMessage: '[A004001] Authlete has successfully issued a ticket to the service (API Key = 21653835348762) for the authorization request from the client (ID = 26478243745571). [response_type=code, openid=false]' acrEssential: false action: INTERACTION client: clientId: 26478243745571 clientIdAlias: my-client clientIdAliasEnabled: true clientName: My updated client logo_uri: https://my-client.example.com/logo.png number: 6164 clientIdAliasUsed: false display: PAGE maxAge: 0 scopes: - defaultEntry: false description: A permission to read your history. name: history.read - defaultEntry: false description: A permission to read your timeline. name: timeline.read service: apiKey: 21653835348762 clientIdAliasEnabled: true number: 5041 serviceName: My updated service ticket: hXoY87t_t23enrVHWxpXNP5FfVDhDypD3T6H6lt4IPA links: authz_issue: $ref: '#/components/links/authz_issue' authz_fail: $ref: '#/components/links/authz_fail' token_exchange: $ref: '#/components/links/token_exchange' token_issue_direct: $ref: '#/components/links/token_issue_direct' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_authorization_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "parameters": "response_type=code&client_id=26478243745571&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&scope=timeline.read+history.read&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationRequest req = new AuthorizationRequest(); req.setParameters(...); api.authorization(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = AuthorizationRequest() req.parameters = ... api.authorization(req) ' tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/fail: post: summary: Fail Authorization Request x-badges: - color: red label: Core API description: 'This API generates a content of an error authorization response that the authorization server implementation returns to the client application. ' x-mint: metadata: description: This API generates a content of an error authorization response that the authorization server implementation returns to the client application. content: ' This API is supposed to be called from within the implementation of the authorization endpoint of the service in order to generate an error response to the client application. The description of the `/auth/authorization` API describes the timing when this API should be called. The response from `/auth/authorization/fail` API has some 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 authorization server 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". Authlete recommends `application/json` as the content type. 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 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted or expired) and that the reason of the invalidity was probably due to the end-user''s too-delayed response to the authorization UI. A response with HTTP status of "400 Bad Request" should be returned to the client application and Authlete recommends `application/json` as the content type. 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} ``` The endpoint implementation may return another different response to the client application since "400 Bad Request" is not required by OAuth 2.0. ## LOCATION When the value of `action` is `LOCATION`, it means that the response to the client application must be "302 Found" with Location header. The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token and/or an access token (on success) or (2) an error code (on failure), so it can be used as the value of `Location` header. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 302 Found Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORM When the value of `action` is `FORM`, it means that the response to the client application must be 200 OK with an HTML which triggers redirection by JavaScript. This happens when the authorization request from the client application contained `response_mode=form_post`. The value of `responseContent` is an HTML which 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 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_fail_request' example: ticket: qA7wGybwArICpbUSutrf5Xc9-i1fHE0ySOHxR1eBoBQ reason: NOT_AUTHENTICATED application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_fail_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_fail_response' example: resultCode: A004201 resultMessage: '[A004201] The authorization request from the service does not contain ''parameters'' parameter.' action: BAD_REQUEST responseContent: '{\"error_description\":\"[A004201] The authorization request from the service does not contain ''parameters'' parameter.\",\"error\":\"invalid_request\",\"error_uri\":\"https://docs.authlete.com/#A004201\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_authorization_fail_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization/fail \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q", "reason": "NOT_AUTHENTICATED" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationFailRequest req = new AuthorizationFailRequest(); req.setTicket("c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q"); req.setReason(AuthorizationFailRequest.Reason.NOT_AUTHENTICATED); api.authorizationFail(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = AuthorizationFailRequest() req.ticket = ''c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q'' req.reason = AuthorizationFailReason.NOT_AUTHENTICATED api.authorizationFail(req) ' tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/issue: post: summary: Issue Authorization Response x-badges: - color: red label: Core API description: 'This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. ' x-mint: metadata: description: This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. content: ' This API is supposed to be called from within the implementation of the authorization endpoint of the service in order to generate a successful response to the client application. The description of the `/auth/authorization` API describes the timing when this API should be called and the meaning of request parameters. See [ISSUE] in `NO_INTERACTION`. The response from `/auth/authorization/issue` API has some 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 authorization server 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 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 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## BAD_REQUEST When the value of "action" is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted or expired) and that the reason of the invalidity was probably due to the end-user''s too-delayed response to the authorization UI. The HTTP status of the response returned to the client application should be "400 Bad Request" and the content type should be `application/json` although OAuth 2.0 specification does not mention the format of the error response. 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} ``` The endpoint implementation may return another different response to the client application since "400 Bad Request" is not required by OAuth 2.0. ## LOCATION When the value of `action` is `LOCATION`, it means that the response to the client application should be "302 Found" with `Location` header. The value of `responseContent` is a redirect URI which contains (1) an authorization code, an ID token and/or an access token (on success) or (2) an error code (on failure), so it can be used as the value of `Location` header. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 302 Found Location: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORM When the value of `action` is `FORM`, it means that the response to the client application should be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization request from the client contains `response_mode=form_post` request parameter. The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`, 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 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_issue_request' example: ticket: FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_issue_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_issue_response' example: resultCode: A040001 resultMessage: '[A040001] The authorization request was processed successfully.' accessTokenDuration: 0 accessTokenExpiresAt: 0 action: LOCATION authorizationCode: Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo responseContent: https://my-client.example.com/cb1?code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&iss=https%3A%2F%2Fmy-service.example.com '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_authorization_issue_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/authorization/issue \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc", "subject": "john" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationIssueRequest req = new AuthorizationIssueRequest(); req.setTicket("FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc"); req.setSubject("john"); api.authorizationIssue(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = AuthorizationIssueRequest() req.ticket = ''FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc'' req.subject = ''john'' api.authorizationIssue(req) ' tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/ticket/info: post: operationId: getAuthorizationTicketInfo summary: Get Ticket Information parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_info_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_ticket_info_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_info_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' tags: - Authorization Endpoint /api/{serviceId}/auth/authorization/ticket/update: post: operationId: updateAuthorizationTicket summary: Update Ticket Information parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_update_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_ticket_update_request' responses: '200': description: Authorization ticket updated successfully content: application/json: schema: $ref: '#/components/schemas/authorization_ticket_update_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' tags: - Authorization Endpoint components: schemas: 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 - LOCATION - FORM - NO_INTERACTION - INTERACTION description: The next action that the authorization server implementation should take. client: $ref: '#/components/schemas/client_limited_authorization' display: $ref: '#/components/schemas/display' maxAge: type: integer format: int32 description: 'The maximum authentication age. This value comes from `max_age` request parameter, or `defaultMaxAge` configuration parameter of the client application when the authorization request does not contain `max_age` request parameter. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), max_age" for `max_age` request parameter, and see "[OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), default_max_age" for `defaultMaxAge` configuration parameter. ' service: $ref: '#/components/schemas/service' scopes: type: array items: $ref: '#/components/schemas/scope' description: "The scopes that the client application requests. This value comes from `scope` request parameter.\nIf the request does not contain `scope` parameter, this parameter is a list of scopes which are registered as default.\nIf the authorization request does not have `scope` request parameter and the service has not registered any default scope,\nthe value of this parameter is `null`.\nIt is ensured that scopes listed by this parameters are contained in the list of supported scopes which are specified\nby `supportedScopes` configuration parameter of the service. Unsupported scopes in the authorization request do not cause\nan error and are just ignored.\nOpenID Connect defines some scope names which need to be treated specially. The table below lists the special scope names.\n| Name | Description |\n| --- | --- |\n| `openid` | This scope must be contained in `scope` request parameter to promote an OAuth 2.0 authorization request to an OpenID Connect request. It is described in \"[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), scope\". |\n| `profile` | This scope is used to request some claims to be embedded in the ID token. The claims are `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, and `updated_at`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). |\n| `email` | This scope is used to request some claims to be embedded in the ID token. The claims are `email` and `email_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). |\n| `address` | This scope is used to request `address` claim to be embedded in the ID token. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims).\n The format of `address` claim is not a simple string. It is described in [OpenID Connect Core 1.0, 5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim). |\n| `phone` | This scope is used to request some claims to be embedded in the ID token. The claims are `phone_number` and `phone_number_verified`. It is described in [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims). |\n| `offline_access` | The following is an excerpt about this scope from [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess).\n> This scope value requests that an OAuth 2.0 Refresh Token be issued that can be used to obtain an Access Token that grants access to the end-user's userinfo endpoint even when the end-user is not present (not logged in).\n|\nNote that, if `response_type` request parameter does not contain code, `offline_acccess` scope is removed from this list even\nwhen scope request parameter contains `offline_access`. This behavior is a requirement written in\n[OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess).\n" uiLocales: type: array items: type: string description: 'The locales that the client application presented as candidates to be used for UI. This value comes from `ui_locales` request parameter. The format of `ui_locales` is a space-separated list of language tag values defined in [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646). See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), ui_locales" for details. It is ensured that locales listed by this parameters are contained in the list of supported UI locales which are specified by `supportedUiLocales` configuration parameter of the service. Unsupported UI locales in the authorization request do not cause an error and are just ignored. ' claimsLocales: type: array items: type: string description: 'End-user''s preferred languages and scripts for claims. This value comes from `claims_locales` request parameter. The format of `claims_locales` is a space-separated list of language tag values defined in [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646). See "[OpenID Connect Core 1.0, 5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)" for details. It is ensured that locales listed by this parameters are contained in the list of supported claim locales which are specified by `supportedClaimsLocales` configuration parameter of the service. Unsupported claim locales in the authorization request do not cause an error and are just ignored. ' claims: type: array items: type: string description: 'The list of claims that the client application requests to be embedded in the ID token. The value comes from (1) `id_token` in `claims` request parameter [1] and/or (2) special scopes (`profile`, `email`, `address` and `phone`) which are expanded to claims. See [OpenID Connect Core 1.0, 5.5. Requesting Claims using the "claims" Request Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter) for `claims` request parameter, and see [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for the special scopes. ' acrEssential: type: boolean description: 'This boolean value indicates whether the authentication of the end-user must be one of the ACRs (Authentication Context Class References) listed in `acrs` parameter. This parameter becomes `true` only when (1) the authorization request contains `claims` request parameter and (2) `acr` claim is in it, and (3) `essential` property of the `acr` claim is `true`. See [OpenID Connect Core 1.0, 5.5.1.1. Requesting the "acr" Claim](https://openid.net/specs/openid-connect-core-1_0.html#acrSemantics) for details. ' clientIdAliasUsed: type: boolean description: '`true` if the value of the `client_id` request parameter included in the authorization request is the client ID alias. `false` if the value is the original numeric client ID. ' acrs: type: array items: type: string description: 'The list of ACRs (Authentication Context Class References) one of which the client application requests to be satisfied for the authentication of the end-user. This value comes from `acr_values` request parameter or `defaultAcrs` configuration parameter of the client application. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), acr_values" for `acr_values` request parameter, and see "[OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata), default_acr_values" for `defaultAcrs` configuration parameter. ' subject: type: string description: 'The subject (= unique user ID managed by the authorization server implementation) that the client application expects to grant authorization. The value comes from `sub` claim in `claims` request parameter. ' loginHint: type: string description: A hint about the login identifier of the end-user. The value comes from `login_hint` request parameter. prompts: type: array items: $ref: '#/components/schemas/prompt' description: The list of values of prompt request parameter. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), prompt" for prompt request parameter. lowestPrompt: $ref: '#/components/schemas/prompt' requestObjectPayload: type: string description: 'The payload part of the request object. The value of this proprty is `null` if the authorization request does not include a request object. ' idTokenClaims: type: string description: 'The value of the `id_token` property in the claims request parameter or in the claims property in a request object. ' x-mint: metadata: description: The value of the `id_token` property in the claims request parameter or in the claims property in a request object. content: "\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 the 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.\nYou can find `userinfo` and `id_token` are top-level properties.\n\n```json\n{\n \"userinfo\":\n {\n \"given_name\": { \"essential\": true },\n \"nickname\": null,\n \"email\": { \"essential\": true },\n \"email_verified\": { \"essential\": true },\n \"picture\": null,\n \"http://example.info/claims/groups\": null\n },\n \"id_token\":\n {\n \"auth_time\": { \"essential\": true },\n \"acr\": { \"values\": [ \"urn:mace:incommon:iap:silver\" ] }\n }\n}\n```\n\nThis value of this property is the value of the `id_token` 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{\n \"auth_time\": { \"essential\": true },\n \"acr\": { \"values\": [ \"urn:mace:incommon:iap:silver\" ] }\n}\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,\nthis property holds the former value.\n\n" userInfoClaims: type: string description: 'The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object. ' x-mint: metadata: description: The value of the `userinfo` property in the `claims` request parameter or in the `claims` property in a request object. content: "\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 the 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{\n \"userinfo\":\n {\n \"given_name\": { \"essential\": true },\n \"nickname\": null,\n \"email\": { \"essential\": true },\n \"email_verified\": { \"essential\": true },\n \"picture\": null,\n \"http://example.info/claims/groups\": null\n },\n \"id_token\":\n {\n \"auth_time\": { \"essential\": true },\n \"acr\": { \"values\": [ \"urn:mace:incommon:iap:silver\" ] }\n }\n}\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{\n \"given_name\": { \"essential\": true },\n \"nickname\": null,\n \"email\": { \"essential\": true },\n \"email_verified\": { \"essential\": true },\n \"picture\": null,\n \"http://example.info/claims/groups\": null\n}\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\n" 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' purpose: type: string description: 'The `purpose` request parameter is defined in [9. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#name-transaction-specific-purpos) of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) as follows: > purpose: OPTIONAL. String describing the purpose for obtaining certain user data from the OP. The purpose MUST NOT be shorter than 3 characters and MUST NOT be longer than 300 characters. If these rules are violated, the authentication request MUST fail and the OP returns an error invalid_request to the RP. ' 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. ' ticket: type: string description: 'A ticket issued by Authlete to the service implementation. This is needed when the service implementation calls either `/auth/authorization/fail` API or `/auth/authorization/issue` API. ' 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. ' requestedClaimsForTx: type: array items: type: string description: '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 { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "userinfo": { "::18_or_over": null, ":nationality_usa": null } } ``` The example above assumes that a transformed claim named `18_or_over` is predefined by the authorization server like below. ```json { "18_or_over": { "claim": "birthdate", "fn": [ "years_ago", [ "gte", 18 ] ] } } ``` 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 { "birthdate": "1970-01-23", "nationalities": [ "DEU", "USA" ] } ``` ' 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. ' 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. ' claimsAtUserInfo: type: array items: type: string description: 'The list of claims that the client application requests to be embedded in userinfo responses. The value comes from the `"scope"` and `"claims"` request parameters of the original authorization request. ' credentialOfferInfo: $ref: '#/components/schemas/credential_offer_info' issuableCredentials: type: string description: 'The information about the **issuable credentials** that can be obtained by presenting the access token that will be issued as a result of the authorization request. ' nativeSsoRequested: type: boolean description: 'Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied: ' x-mint: metadata: description: 'Flag which indicates whether [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html) is requested. This property should be set to `true` when all the following conditions are satisfied:' content: ' - The service supports Native SSO (see `nativeSsoSupported` property of Service). - The service supports the `openid` and `device_sso` scopes. - The client is allowed to request the `openid` and `device_sso` scopes. - The authorization request includes the `openid` and `device_sso` scopes. - The authorization request''s `response_type` includes `code`. NOTE: If this property is set to `true`, the `sessionId` request parameter must be provided to the `/auth/authorization/issue` API. ' 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. ' authorization_issue_request: type: object required: - ticket - subject properties: ticket: type: string description: 'The ticket issued from Authlete `/auth/authorization` API. ' subject: type: string description: 'The subject (= a user account managed by the service) who has granted authorization to the client application. ' authTime: type: integer format: int64 description: 'The time when the authentication of the end-user occurred. Its value is the number of seconds from `1970-01-01`. ' acr: type: string description: The Authentication Context Class Reference performed for the end-user authentication. claims: type: string description: 'The claims of the end-user (= pieces of information about the end-user) in JSON format. See [OpenID Connect Core 1.0, 5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) for details about the format. ' properties: type: array items: $ref: '#/components/schemas/property' description: Extra properties to associate with an access token and/or an authorization code. scopes: type: array items: type: string description: 'Scopes to associate with an access token and/or an authorization code. If a non-empty string array is given, it replaces the scopes specified by the original authorization request. ' sub: type: string description: 'The value of the `sub` claim to embed in an ID token. If this request parameter is `null` or empty, the value of the `subject` request parameter is used as the value of the `sub` claim. ' idtHeaderParams: type: string description: 'JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request. ' claimsForTx: type: string description: 'Claim key-value pairs that are used to compute transformed claims. ' consentedClaims: type: array items: type: string description: 'the claims that the user has consented for the client application to know. ' authorizationDetails: $ref: '#/components/schemas/authz_details' jwtAtClaims: type: string description: 'Additional claims that are added to the payload part of the JWT access token. ' accessToken: type: string description: 'The representation of an access token that may be issued as a result of the Authlete API call. ' 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. ' sessionId: type: string description: 'The session ID of the user''s authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`. ' x-mint: metadata: description: The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`. content: ' NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested` property with a value of `true`, the `sessionId` request parameter must be provided to the `/auth/authorization/issue` API. ' 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. ' 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: "\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/authorization` 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/authorization` API response). The authorization\nserver implementation 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 \"{\\\"birthdate\\\":\\\"1970-01-23\\\",\\\"nationalities\\\":[\\\"DEU\\\",\\\"USA\\\"]}\"\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{\n \"transformed_claims\": {\n \"nationality_usa\": {\n \"claim\": \"nationalities\",\n \"fn\": [\n [ \"eq\", \"USA\" ],\n \"any\"\n ]\n }\n },\n \"id_token\": {\n \"verified_claims\": [\n {\n \"verification\": { \"trust_framework\": { \"value\": \"gold\" } },\n \"claims\": { \"::18_or_above\": null }\n },\n {\n \"verification\": { \"trust_framework\": { \"value\": \"silver\" } },\n \"claims\": { \":nationality_usa\": null }\n }\n ]\n }\n}\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 \"{\\\"birthdate\\\":\\\"1970-01-23\\\"}\",\n \"{\\\"nationalities\\\":[\\\"DEU\\\",\\\"USA\\\"]}\"\n]\n```\n\n" authorization_fail_request: type: object required: - ticket - reason properties: ticket: type: string description: 'The ticket issued from Authlete `/auth/authorization` API. ' reason: type: string enum: - UNKNOWN - NOT_LOGGED_IN - MAX_AGE_NOT_SUPPORTED - EXCEEDS_MAX_AGE - DIFFERENT_SUBJECT - ACR_NOT_SATISFIED - DENIED - SERVER_ERROR - NOT_AUTHENTICATED - ACCOUNT_SELECTION_REQUIRED - CONSENT_REQUIRED - INTERACTION_REQUIRED - INVALID_TARGET description: 'The reason of the failure of the authorization request. For more details, see [NO_INTERACTION] in the description of `/auth/authorization` API. ' description: type: string description: 'The custom description about the authorization failure. ' grant_type: type: string description: 'The grant type of the access token when the access token was created. ' enum: - AUTHORIZATION_CODE - IMPLICIT - PASSWORD - CLIENT_CREDENTIALS - REFRESH_TOKEN - CIBA - DEVICE_CODE - TOKEN_EXCHANGE - JWT_BEARER - PRE_AUTHORIZED_CODE client_registration_type: type: string description: "Values for the `client_registration_types` RP metadata and the\n `client_registration_types_supported` OP metadata that are defined in\n [OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html).\n" enum: - AUTOMATIC - EXPLICIT authorization_request: type: object required: - parameters properties: parameters: type: string description: 'OAuth 2.0 authorization request parameters which are the request parameters that the OAuth 2.0 authorization endpoint of the authorization server implementation received from the client application. The value of parameters is either (1) the entire query string when the HTTP method of the request from the client application is `GET` or (2) the entire entity body (which is formatted in `application/x-www-form-urlencoded`) when the HTTP method of the request from the client application is `POST`. ' context: type: string description: 'The arbitrary text to be attached to the ticket that will be issued from the `/auth/authorization` API. The text can be retrieved later by the `/auth/authorization/ticket/info` API and can be updated by the `/auth/authorization/ticket/update` API. The text will be compressed and encrypted when it is saved in the Authlete database. ' 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. ' credential_issuer_metadata: type: object properties: authorizationServers: type: array items: type: string description: 'The identifiers of the authorization servers that the credential issuer relies on for authorization. This property corresponds to the authorization_servers metadata. When the credential issuer works as an authorization server for itself, this property should be omitted. ' credentialIssuer: type: string description: The identifier of a credential request. credentialEndpoint: type: string format: uri description: The URL of the credential endpoint of the credential issuer. batchCredentialEndpoint: type: string format: uri description: The URL of the batch credential endpoint of the credential issuer. deferredCredentialEndpoint: type: string description: The URL of the deferred credential endpoint of the credential issuer. credentialsSupported: type: string description: 'A JSON object describing supported credential configurations. This property corresponds to the credential_configurations_supported metadata. Note: Due to a breaking change in December 2023, this was changed from a JSON array to a JSON object. ' credentialResponseEncryptionAlgValuesSupported: type: array items: type: string description: 'The supported JWE `alg` algorithms for credential response encryption. This property corresponds to the `credential_response_encryption.alg_values_supported` metadata. ' credentialResponseEncryptionEncValuesSupported: type: array items: type: string description: 'The supported JWE `enc` algorithms for credential response encryption. This property corresponds to the `credential_response_encryption.enc_values_supported` metadata. ' requireCredentialResponseEncryption: type: boolean description: 'The boolean flag indicating whether credential response encryption is required. This property corresponds to the `credential_response_encryption.encryption_required metadata`. If this flag is `true`, every credential request to the credential issuer must include the `credential_response_encryption` property. ' authorization_ticket_update_response: type: object properties: info: $ref: '#/components/schemas/authorization_ticket_info' description: Information about the ticket. action: type: string enum: - OK - NOT_FOUND - CALLER_ERROR - AUTHLETE_ERROR description: The result of the /auth/authorization/ticket/info API call. 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. response_type: type: string enum: - NONE - CODE - TOKEN - ID_TOKEN - CODE_TOKEN - CODE_ID_TOKEN - ID_TOKEN_TOKEN - CODE_ID_TOKEN_TOKEN tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. hsk: type: object description: 'Holds information about a key managed in an HSM (Hardware Security Module) ' properties: kty: type: string description: 'The key type (EC or RSA) ' use: type: string description: 'Get the use of the key on the HSM. When the key use is "sig" (signature), the private key on the HSM is used to sign data and the corresponding public key is used to verify the signature. When the key use is "enc" (encryption), the private key on the HSM is used to decrypt encrypted data which have been encrypted with the corresponding public key ' kid: type: string description: 'Key ID for the key on the HSM. ' hsmName: type: string description: 'The name of the HSM. The identifier for the HSM that sits behind the Authlete server. For example, "google". ' handle: type: string description: 'The handle for the key on the HSM. A handle is a base64url-encoded 256-bit random value (43 letters) which is assigned by Authlete on the call of the /api/hsk/create API ' publicKey: type: string description: 'The public key that corresponds to the key on the HSM. ' alg: type: string description: 'The algorithm of the key on the HSM. When the key use is `"sig"`, the algorithm represents a signing algorithm such as `"ES256"`. When the key use is `"enc"`, the algorithm represents an encryption algorithm such as `"RSA-OAEP-256"`. ' authorization_fail_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 - LOCATION - FORM 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. ' authorization_ticket_info_request: type: object required: - ticket properties: ticket: type: string description: The ticket that has been issued from the `/auth/authorization` API. display: type: string description: 'The display mode which the client application requests by `display` request parameter. When the authorization request does not have `display` request parameter, `PAGE` is set as the default value. It is ensured that the value of `display` is one of the supported display modes which are specified by `supportedDisplays` configuration parameter of the service. If the display mode specified by the authorization request is not supported, an error is raised. Values for this property correspond to the values listed in "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), display". ' enum: - PAGE - POPUP - TOUCH - WAP 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. ' jws_alg: type: string nullable: true description: "The signature algorithm for JWT. This value is represented on 'alg' attribute\nof the header of JWT.\n\nit's semantics depends upon where is this defined, for instance:\n - as service accessTokenSignAlg value, it defines that access token are JWT and the algorithm used to sign it. Check your [KB article](https://kb.authlete.com/en/s/oauth-and-openid-connect/a/jwt-based-access-token).\n - as client authorizationSignAlg value, it represents the signature algorithm used when [creating a JARM response](https://kb.authlete.com/en/s/oauth-and-openid-connect/a/enabling-jarm).\n - or as client requestSignAlg value, it specifies which is the expected signature used by [client on a Request Object](https://kb.authlete.com/en/s/oauth-and-openid-connect/a/request-objects).\n" enum: - NONE - HS256 - HS384 - HS512 - RS256 - RS384 - RS512 - ES256 - ES384 - ES512 - PS256 - PS384 - PS512 - ES256K - EdDSA 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 sns_credentials: type: object properties: sns: type: string description: SNS. apiKey: type: string description: API key. apiSecret: type: string description: API secret. attachment_type: type: string description: "Supported attachment types. This property corresponds to the `attachments_supported`\n server metadata which was added by the third implementer's draft of OpenID Connect\n for Identity Assurance 1.0.\n" enum: - EMBEDDED - EXTERNAL authorization_ticket_info_response: type: object properties: info: $ref: '#/components/schemas/authorization_ticket_info' description: Information about the ticket. action: type: string enum: - OK - NOT_FOUND - CALLER_ERROR - AUTHLETE_ERROR description: The result of the `/auth/authorization/ticket/info` API call. 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. authorization_ticket_update_request: type: object required: - ticket - info properties: ticket: type: string description: The ticket. info: type: string description: The information about the ticket. authorization_ticket_info: type: object properties: context: type: string description: 'The arbitrary text attached to the ticket. ' grant_scope: type: object properties: scope: type: string description: 'Space-delimited scopes. ' resource: type: array items: type: string description: 'List of resource indicators. ' trust_anchor: type: object properties: entityId: type: string description: 'the entity ID of the trust anchor ' jwks: type: string description: 'the JWK Set document containing public keys of the trust anchor ' 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. ' fapi_mode: type: string enum: - FAPI1_ADVANCED - FAPI1_BASELINE - FAPI2_MESSAGE_SIGNING_AUTH_REQ - FAPI2_MESSAGE_SIGNING_AUTH_RES - FAPI2_MESSAGE_SIGNING_INTROSPECTION_RES - FAPI2_SECURITY prompt: type: string description: 'The prompt that the UI displayed to the end-user must satisfy as the minimum level. This value comes from `prompt` request parameter. When the authorization request does not contain `prompt` request parameter, `CONSENT` is used as the default value. See "[OpenID Connect Core 1.0, 3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), prompt" for `prompt` request parameter. ' enum: - NONE - LOGIN - CONSENT - SELECT_ACCOUNT - CREATE service: type: object example: number: 715948317 serviceName: My Test Service issuer: https://example.com supportedScopes: - profile - email - openid supportedResponseTypes: - CODE supportedGrantTypes: - AUTHORIZATION_CODE - REFRESH_TOKEN properties: number: type: integer format: int32 readOnly: true description: The sequential number of the service. The value of this property is assigned by Authlete. serviceName: type: string description: The name of this service. issuer: type: string description: 'The issuer identifier of the service. A URL that starts with https:// and has no query or fragment component. The value of this property is used as `iss` claim in an [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and `issuer` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' description: type: string description: The description about the service. apiKey: type: integer format: int64 readOnly: true description: The service ID used in Authlete API calls. The value of this property is assigned by Authlete. apiSecret: type: string readOnly: true description: "The API secret of this service. This value is assigned by Authlete and \nis used for service authentication in API calls.\n" tokenBatchNotificationEndpoint: type: string format: uri description: "The endpoint for batch token notifications. This endpoint is called when \nmultiple tokens are issued or revoked in a batch operation.\n" clientAssertionAudRestrictedToIssuer: type: boolean description: "The flag indicating whether the audience of client assertion JWTs must \nmatch the issuer identifier of this service.\n" serviceOwnerNumber: type: integer format: int32 readOnly: true description: "The number of the organization that owns this service. This value is \nassigned by Authlete.\n" clientsPerDeveloper: type: integer format: int32 description: 'The maximum number of client applications that a developer can have. ' developerAuthenticationCallbackEndpoint: type: string format: uri description: "The endpoint for developer authentication callbacks. This is used when \ndevelopers log into the developer portal.\n" developerAuthenticationCallbackApiKey: type: string description: "The API key for basic authentication at the developer authentication \ncallback endpoint.\n" developerAuthenticationCallbackApiSecret: type: string description: "The API secret for basic authentication at the developer authentication \ncallback endpoint.\n" supportedSnses: type: array items: type: string enum: - FACEBOOK description: "Social login services (SNS) that this service supports for end-user \nauthentication.\n" snsCredentials: type: array items: $ref: '#/components/schemas/sns_credentials' description: "The credentials for social login services (SNS) that are used for \nend-user authentication.\n" clientIdAliasEnabled: type: boolean description: Deprecated. Always `true`. metadata: type: array items: $ref: '#/components/schemas/pair' description: "The `metadata` of the service. The content of the returned array depends on contexts.\nThe predefined service metadata is listed in the following table.\n\n | Key | Description |\n | --- | --- |\n | `clientCount` | The number of client applications which belong to this service. |\n" createdAt: type: integer format: int64 readOnly: true description: 'The time at which this service was created. The value is represented as milliseconds since the UNIX epoch (`1970-01-01`). ' modifiedAt: type: integer format: int64 readOnly: true description: 'The time at which this service was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). ' authenticationCallbackEndpoint: type: string format: uri description: 'A Web API endpoint for user authentication which is to be prepared on the service side. The endpoint must be implemented if you do not implement the UI at the authorization endpoint but use the one provided by Authlete. The user authentication at the authorization endpoint provided by Authlete is performed by making a `POST` request to this endpoint. ' authenticationCallbackApiKey: type: string description: 'API key for basic authentication at the authentication callback endpoint. If the value is not empty, Authlete generates Authorization header for Basic authentication when making a request to the authentication callback endpoint. ' authenticationCallbackApiSecret: type: string description: API secret for `basic` authentication at the authentication callback endpoint. supportedAcrs: readOnly: true type: array items: type: string description: 'Values of acrs (authentication context class references) that the service supports. The value of this property is used as `acr_values_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' supportedGrantTypes: type: array items: $ref: '#/components/schemas/grant_type' description: 'Values of `grant_type` request parameter that the service supports. The value of this property is used as `grant_types_supported property` in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' supportedResponseTypes: type: array items: $ref: '#/components/schemas/response_type' description: 'Values of `response_type` request parameter that the service supports. Valid values are listed in Response Type. The value of this property is used as `response_types_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' supportedAuthorizationDetailsTypes: type: array items: type: string description: 'The supported data types that can be used as values of the type field in `authorization_details`. This property corresponds to the `authorization_details_types_supported` metadata. See "OAuth 2.0 Rich Authorization Requests" (RAR) for details. ' supportedServiceProfiles: type: array items: $ref: '#/components/schemas/service_profile' description: 'The profiles that this service supports. ' errorDescriptionOmitted: type: boolean description: 'The flag to indicate whether the `error_description` response parameter is omitted. According to [RFC 6749](https://tools.ietf.org/html/rfc6749), an authorization server may include the `error_description` response parameter in error responses. If `true`, Authlete does not embed the `error_description` response parameter in error responses. ' errorUriOmitted: type: boolean description: 'The flag to indicate whether the `error_uri` response parameter is omitted. According to [RFC 6749](https://tools.ietf.org/html/rfc6749), an authorization server may include the `error_uri` response parameter in error responses. If `true`, Authlete does not embed the `error_uri` response parameter in error responses. ' authorizationEndpoint: type: string format: uri description: 'The authorization endpoint of the service. A URL that starts with `https://` and has no fragment component. For example, `https://example.com/auth/authorization`. The value of this property is used as `authorization_endpoint` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' directAuthorizationEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct authorization endpoint is enabled or not. The path of the endpoint is `/api/auth/authorization/direct/service-api-key`. ' supportedUiLocales: type: array items: type: string description: 'UI locales that the service supports. Each element is a language tag defined in [RFC 5646](https://tools.ietf.org/html/rfc5646). For example, `en-US` and `ja-JP`. The value of this property is used as `ui_locales_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' supportedDisplays: type: array items: $ref: '#/components/schemas/display' description: 'Values of `display` request parameter that service supports. The value of this property is used as `display_values_supported` property in the Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' pkceRequired: type: boolean description: 'The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow. If `true`, `code_challenge` request parameter is always required for authorization requests using Authorization Code Flow. See [RFC 7636](https://tools.ietf.org/html/rfc7636) (Proof Key for Code Exchange by OAuth Public Clients) for details about `code_challenge` request parameter. ' pkceS256Required: type: boolean description: 'The flag to indicate whether `S256` is always required as the code challenge method whenever [PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636) is used. If this flag is set to `true`, `code_challenge_method=S256` must be included in the authorization request whenever it includes the `code_challenge` request parameter. Neither omission of the `code_challenge_method` request parameter nor use of plain (`code_challenge_method=plain`) is allowed. ' authorizationResponseDuration: type: integer format: int64 description: 'The duration of authorization response JWTs in seconds. [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) defines new values for the `response_mode` request parameter. They are `query.jwt`, `fragment.jwt`, `form_post.jwt` and `jwt`. If one of them is specified as the response mode, response parameters from the authorization endpoint will be packed into a JWT. This property is used to compute the value of the `exp` claim of the JWT. ' authorizationCodeDuration: type: integer format: int64 description: 'The duration of authorization codes in seconds. ' tokenEndpoint: type: string format: uri description: 'The [token endpoint](https://tools.ietf.org/html/rfc6749#section-3.2) of the service. A URL that starts with `https://` and has not fragment component. For example, `https://example.com/auth/token`. The value of this property is used as `token_endpoint` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' directTokenEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct token endpoint is enabled or not. The path of the endpoint is `/api/auth/token/direct/service-api-key`. ' supportedTokenAuthMethods: type: array items: $ref: '#/components/schemas/client_auth_method' description: 'Client authentication methods supported by the token endpoint of the service. The value of this property is used as `token_endpoint_auth_methods_supports` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' missingClientIdAllowed: type: boolean description: 'The flag to indicate token requests from public clients without the `client_id` request parameter are allowed when the client can be guessed from `authorization_code` or `refresh_token`. This flag should not be set unless you have special reasons. ' revocationEndpoint: type: string format: uri description: 'The [revocation endpoint](https://tools.ietf.org/html/rfc7009) of the service. A URL that starts with `https://`. For example, `https://example.com/auth/revocation`. ' directRevocationEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct revocation endpoint is enabled or not. The URL of the endpoint is `/api/auth/revocation/direct/service-api-key`. ' supportedRevocationAuthMethods: type: array items: $ref: '#/components/schemas/client_auth_method' description: 'Client authentication methods supported at the revocation endpoint. ' introspectionEndpoint: type: string description: The URI of the introspection endpoint. format: uri directIntrospectionEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct userinfo endpoint is enabled or not. The path of the endpoint is `/api/auth/userinfo/direct/{serviceApiKey}`. ' supportedIntrospectionAuthMethods: type: array description: 'Client authentication methods supported at the introspection endpoint. ' items: $ref: '#/components/schemas/client_auth_method' pushedAuthReqEndpoint: type: string description: 'The URI of the pushed authorization request endpoint. This property corresponds to the `pushed_authorization_request_endpoint` metadata defined in "[5. Authorization Server Metadata](https://tools.ietf.org/html/draft-lodderstedt-oauth-par#section-5)" of OAuth 2.0 Pushed Authorization Requests. ' format: uri pushedAuthReqDuration: type: integer format: int64 description: 'The duration of pushed authorization requests in seconds. ' x-mint: metadata: description: The duration of pushed authorization requests in seconds. content: ' [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par) defines an endpoint (called "pushed authorization request endpoint") which client applications can register authorization requests into and get corresponding URIs (called "request URIs") from. The issued URIs represent the registered authorization requests. The client applications can use the URIs as the value of the `request_uri` request parameter in an authorization request. The property represents the duration of registered authorization requests and is used as the value of the `expires_in` parameter in responses from the pushed authorization request endpoint. ' parRequired: type: boolean description: 'The flag to indicate whether this service requires that clients use the pushed authorization request endpoint. This property corresponds to the `require_pushed_authorization_requests` server metadata defined in [OAuth 2.0 Pushed Authorization Requests](https://tools.ietf.org/html/draft-lodderstedt-oauth-par). ' requestObjectRequired: type: boolean description: 'The flag to indicate whether this service requires that authorization requests always utilize a request object by using either request or `request_uri` request parameter. If this flag is set to `true` and the value of `traditionalRequestObjectProcessingApplied` is `false`, the value of `require_signed_request_object` server metadata of this service is reported as `true` in the discovery document. The metadata is defined in JAR (JWT Secured Authorization Request). That `require_signed_request_object` is `true` means that authorization requests which don''t conform to the JAR specification are rejected. ' traditionalRequestObjectProcessingApplied: type: boolean description: 'The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request). ' x-mint: metadata: description: The flag to indicate whether a request object is processed based on rules defined in [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) or JAR (JWT Secured Authorization Request). content: "\nDifferences between rules in OpenID Connect Core 1.0 and ones in JAR are as follows.\n - JAR requires that a request object be always -signed.\n - JAR does not allow request parameters outside a request object to be referred to.\n - OIDC Core 1.0 requires that response_type request parameter exist outside a request object even if the request object includes the request parameter.\n - OIDC Core 1.0 requires that scope request parameter exist outside a request object if the authorization request is an\n - OIDC request even if the request object includes the request parameter.\n\nIf this flag is set to `false` and the value of `requestObjectRequired` is `true`, the value of\n`require_signed_request_object` server metadata of this service\nis reported as `true` in the discovery document. The metadata is defined in JAR (JWT Secured\nAuthorization Request). That `require_signed_request_object` is `true` means that authorization\nrequests which don't conform to the JAR specification are rejected.\n\n" mutualTlsValidatePkiCertChain: type: boolean description: 'The flag to indicate whether this service validates certificate chains during PKI-based client mutual TLS authentication. ' trustedRootCertificates: type: array items: type: string description: 'The list of root certificates trusted by this service for PKI-based client mutual TLS authentication. ' mtlsEndpointAliases: type: array items: $ref: '#/components/schemas/named_uri' description: 'The MTLS endpoint aliases. ' x-mint: metadata: description: The MTLS endpoint aliases. content: "\nThis property corresponds to the mtls_endpoint_aliases metadata defined in \"5. Metadata for Mutual TLS Endpoint Aliases\" of [OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/rfc8705/).\n\nThe aliases will be embedded in the response from the discovery endpoint like the following.\n\n```json\n{\n ......,\n \"mtls_endpoint_aliases\": {\n \"token_endpoint\": \"https://mtls.example.com/token\",\n \"revocation_endpoint\": \"https://mtls.example.com/revo\",\n \"introspection_endpoint\": \"https://mtls.example.com/introspect\"\n }\n}\n```\n\n" accessTokenType: type: string description: 'The access token type. This value is used as the value of `token_type` property in access token responses. If this service complies with [RFC 6750](https://tools.ietf.org/html/rfc6750), the value of this property should be `Bearer`. See [RFC 6749 (OAuth 2.0), 7.1. Access Token Types](https://tools.ietf.org/html/rfc6749#section-7.1) for details. ' tlsClientCertificateBoundAccessTokens: type: boolean description: 'The flag to indicate whether this service supports issuing TLS client certificate bound access tokens. ' accessTokenDuration: type: integer format: int64 description: 'The duration of access tokens in seconds. This value is used as the value of `expires_in` property in access token responses. `expires_in` is defined [RFC 6749, 5.1. Successful Response](https://tools.ietf.org/html/rfc6749#section-5.1). ' singleAccessTokenPerSubject: type: boolean description: 'The flag to indicate whether the number of access tokens per subject (and per client) is at most one or can be more. If `true`, an attempt to issue a new access token invalidates existing access tokens that are associated with the same subject and the same client. Note that, however, attempts by [Client Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.4) do not invalidate existing access tokens because access tokens issued by Client Credentials Flow are not associated with any end-user''s subject. Also note that an attempt by [Refresh Token Flow](https://tools.ietf.org/html/rfc6749#section-6) invalidates the coupled access token only and this invalidation is always performed regardless of whether the value of this setting item is `true` or `false`. ' accessTokenSignAlg: $ref: '#/components/schemas/jws_alg' accessTokenSignatureKeyId: type: string description: 'The key ID to identify a JWK used for signing access tokens. A JWK Set can be registered as a property of a service. A JWK Set can contain 0 or more JWKs. Authlete Server has to pick up one JWK for signing from the JWK Set when it generates a JWT-based access token. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for access token signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. ' refreshTokenDuration: type: integer format: int64 description: The duration of refresh tokens in seconds. The related specifications have no requirements on refresh token duration, but Authlete sets expiration for refresh tokens. refreshTokenDurationKept: type: boolean description: 'The flag to indicate whether the remaining duration of the used refresh token is taken over to the newly issued refresh token. ' refreshTokenDurationReset: type: boolean description: 'The flag which indicates whether duration of refresh tokens are reset when they are used even if the `refreshTokenKept` property of this service set to is `true` (= even if "Refresh Token Continuous Use" is "Kept"). This flag has no effect when the `refreshTokenKept` property is set to `false`. In other words, if this service issues a new refresh token on every refresh token request, the refresh token will have fresh duration (unless `refreshTokenDurationKept` is set to `true`) and this `refreshTokenDurationReset` property is not referenced. ' refreshTokenKept: type: boolean description: 'The flag to indicate whether a refresh token remains unchanged or gets renewed after its use. If `true`, a refresh token used to get a new access token remains valid after its use. Otherwise, if `false`, a refresh token is invalidated after its use and a new refresh token is issued. See [RFC 6749 6. Refreshing an Access Token](https://tools.ietf.org/html/rfc6749#section-6), as to how to get a new access token using a refresh token. ' supportedScopes: type: array items: $ref: '#/components/schemas/scope' description: 'Scopes supported by the service. ' x-mint: metadata: description: Scopes supported by the service. content: ' Authlete strongly recommends that the service register at least the following scopes. | Name | Description | | --- | --- | | openid | A permission to get an ID token of an end-user. The `openid` scope appears in [OpenID Connect Core 1.0, 3.1.2.1. Authentication Request, scope](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Without this scope, Authlete does not allow `response_type` request parameter to have values other than code and token. | | profile | A permission to get information about `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale` and `updated_at` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | email | A permission to get information about `email` and `email_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | address | A permission to get information about address from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) and [5.1.1. Address Claim](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) for details. | | phone | A permission to get information about `phone_number` and `phone_number_verified` from the user info endpoint. See [OpenID Connect Core 1.0, 5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) for details. | | offline_access | A permission to get information from the user info endpoint even when the end-user is not present. See [OpenID Connect Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess) for details. | The value of this property is used as `scopes_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' scopeRequired: type: boolean description: 'The flag to indicate whether requests that request no scope are rejected or not. ' x-mint: metadata: description: The flag to indicate whether requests that request no scope are rejected or not. content: ' When a request has no explicit `scope` parameter and the service''s pre-defined default scope set is empty, the authorization server regards the request requests no scope. When this flag is set to `true`, requests that request no scope are rejected. The requirement below excerpted from [RFC 6749 Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3) does not explicitly mention the case where the default scope set is empty. > If the client omits the scope parameter when requesting authorization, the authorization server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope. However, if you interpret *"the default scope set exists but is empty"* as *"the default scope set does not exist"* and want to strictly conform to the requirement above, this flag has to be `true`. ' idTokenDuration: type: integer format: int64 description: '''The duration of [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)s in seconds. This value is used to calculate the value of `exp` claim in an ID token.'' ' allowableClockSkew: type: integer format: int32 description: 'The allowable clock skew between the server and clients in seconds. The clock skew is taken into consideration when time-related claims in a JWT (e.g. `exp`, `iat`, `nbf`) are verified. ' supportedClaimTypes: type: array items: $ref: '#/components/schemas/claim_type' description: 'Claim types supported by the service. Valid values are listed in Claim Type. Note that Authlete currently doesn''t provide any API to help implementations for `AGGREGATED` and `DISTRIBUTED`. The value of this property is used as `claim_types_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' supportedClaimLocales: type: array items: type: string description: 'Claim locales that the service supports. Each element is a language tag defined in [RFC 5646](https://tools.ietf.org/html/rfc5646). For example, `en-US` and `ja-JP`. See [OpenID Connect Core 1.0, 5.2. Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts) for details. The value of this property is used as `claims_locales_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' supportedClaims: type: array items: type: string description: 'Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims. ' x-mint: metadata: description: Claim names that the service supports. The standard claim names listed in [OpenID Connect Core 1.0, 5.1. Standard Claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) should be supported. The following is the list of standard claims. content: ' - `sub` - `name` - `given_name` - `family_name` - `middle_name` - `nickname` - `preferred_username` - `profile` - `picture` - `website` - `email` - `email_verified` - `gender` - `birthdate` - `zoneinfo` - `locale` - `phone_number` - `phone_number_verified` - `address` - `updated_at` The value of this property is used as `claims_supported` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). The service may support its original claim names. See [OpenID Connect Core 1.0, 5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims). ' claimShortcutRestrictive: type: boolean description: 'The flag indicating whether claims specified by shortcut scopes (e.g. `profile`) are included in the issued ID token only when no access token is issued. ' x-mint: metadata: description: The flag indicating whether claims specified by shortcut scopes (e.g. `profile`) are included in the issued ID token only when no access token is issued. content: ' To strictly conform to the description below excerpted from [OpenID Connect Core 1.0 Section 5.4](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims), this flag has to be `true`. > The Claims requested by the profile, email, address, and phone scope values are returned from the UserInfo Endpoint, as described in Section 5.3.2, when a response_type value is used that results in an Access Token being issued. However, when no Access Token is issued (which is the case for the response_type value id_token), the resulting Claims are returned in the ID Token. ' jwksUri: type: string format: uri description: 'The URL of the service''s [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) document. For example, `http://example.com/auth/jwks`. Client applications accesses this URL (1) to get the public key of the service to validate the signature of an ID token issued by the service and (2) to get the public key of the service to encrypt an request object of the client application. See [OpenID Connect Core 1.0, 10. Signatures and Encryption](https://openid.net/specs/openid-connect-core-1_0.html#SigEnc) for details. The value of this property is used as `jwks_uri` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' directJwksEndpointEnabled: type: boolean description: '''The flag to indicate whether the direct jwks endpoint is enabled or not. The path of the endpoint is `/api/service/jwks/get/direct/service-api-key`. '' ' jwks: type: string description: 'The content of the service''s [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) document. If this property is not `null` in a `/service/create` request or a `/service/update` request, Authlete hosts the content in the database. This property must not be `null` and must contain pairs of public/private keys if the service wants to support asymmetric signatures for ID tokens and asymmetric encryption for request objects. See [OpenID Connect Core 1.0, 10. Signatures and Encryption](https://openid.net/specs/openid-connect-core-1_0.html#SigEnc) for details. ' idTokenSignatureKeyId: type: string description: 'The key ID to identify a JWK used for ID token signature using an asymmetric key. ' x-mint: metadata: description: The key ID to identify a JWK used for ID token signature using an asymmetric key. content: ' A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has to pick up one JWK for signature from the JWK Set when it generates an ID token and signature using an asymmetric key is required. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for ID token signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5) is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This `idTokenSignatureKeyId` property exists for the purpose described above. For key rotation (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), this mechanism is needed. ' userInfoSignatureKeyId: type: string description: 'The key ID to identify a JWK used for user info signature using an asymmetric key. ' x-mint: metadata: description: The key ID to identify a JWK used for user info signature using an asymmetric key. content: ' A JWK Set can be registered as a property of a Service. A JWK Set can contain 0 or more JWKs (See [RFC 7517](https://tools.ietf.org/html/rfc7517) for details about JWK). Authlete Server has to pick up one JWK for signature from the JWK Set when it is required to sign user info (which is returned from [userinfo endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo)) using an asymmetric key. Authlete Server searches the registered JWK Set for a JWK which satisfies conditions for user info signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a [Key ID](https://tools.ietf.org/html/rfc7517#section-4.5) is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This `userInfoSignatureKeyId` property exists for the purpose described above. For key rotation (OpenID Connect Core 1.0, [10.1.1. Rotation of Asymmetric Signing Keys](http://openid.net/specs/openid-connect-core-1_0.html#RotateSigKeys)), this mechanism is needed. ' authorizationSignatureKeyId: type: string description: 'The key ID to identify a JWK used for signing authorization responses using an asymmetric key. ' x-mint: metadata: description: The key ID to identify a JWK used for signing authorization responses using an asymmetric key. content: ' [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) defines new values for the `response_mode` request parameter. They are `query.jwt`, `fragment.jwt`, `form_post.jwt` and `jwt`. If one of them is specified as the response mode, response parameters from the authorization endpoint will be packed into a JWT. This property is used to compute the value of the `exp` claim of the JWT. Authlete Server searches the JWK Set for a JWK which satisfies conditions for authorization response signature. If the number of JWK candidates which satisfy the conditions is 1, there is no problem. On the other hand, if there exist multiple candidates, a Key ID is needed to be specified so that Authlete Server can pick up one JWK from among the JWK candidates. This property exists to specify the key ID. ' userInfoEndpoint: type: string description: 'The [user info endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo) of the service. A URL that starts with `https://`. For example, `https://example.com/auth/userinfo`. The value of this property is used as `userinfo_endpoint` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' format: uri directUserInfoEndpointEnabled: type: boolean description: 'The flag to indicate whether the direct userinfo endpoint is enabled or not. The path of the endpoint is `/api/auth/userinfo/direct/service-api-key`. ' dynamicRegistrationSupported: type: boolean description: 'The boolean flag which indicates whether the [OAuth 2.0 Dynamic Client Registration Protocol](https://tools.ietf.org/html/rfc7591) is supported. ' registrationEndpoint: type: string description: 'The [registration endpoint](http://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration) of the service. A URL that starts with `https://`. For example, `https://example.com/auth/registration`. The value of this property is used as `registration_endpoint` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' format: uri registrationManagementEndpoint: type: string description: 'The URI of the registration management endpoint. If dynamic client registration is supported, and this is set, this URI will be used as the basis of the client''s management endpoint by appending `/clientid}/` to it as a path element. If this is unset, the value of `registrationEndpoint` will be used as the URI base instead. ' format: uri policyUri: type: string description: 'The URL of the "Policy" of the service. The value of this property is used as `op_policy_uri` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' format: uri tosUri: type: string description: 'The URL of the "Terms Of Service" of the service. The value of this property is used as `op_tos_uri` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' format: uri serviceDocumentation: type: string description: 'The URL of a page where documents for developers can be found. The value of this property is used as `service_documentation` property in the [OpenID Provider Metadata](http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' format: uri backchannelAuthenticationEndpoint: type: string description: 'The URI of backchannel authentication endpoint, which is defined in the specification of [CIBA (Client Initiated Backchannel Authentication)](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html). ' format: uri supportedBackchannelTokenDeliveryModes: type: array items: $ref: '#/components/schemas/delivery_mode' description: 'The supported backchannel token delivery modes. This property corresponds to the `backchannel_token_delivery_modes_supported` metadata. Backchannel token delivery modes are defined in the specification of [CIBA (Client Initiated Backchannel Authentication)](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html). ' backchannelAuthReqIdDuration: type: integer format: int32 description: 'The duration of backchannel authentication request IDs issued from the backchannel authentication endpoint in seconds. This is used as the value of the `expires_in` property in responses from the backchannel authentication endpoint. ' backchannelPollingInterval: type: integer format: int32 description: 'The minimum interval between polling requests to the token endpoint from client applications in seconds. This is used as the value of the `interval` property in responses from the backchannel authentication endpoint. ' backchannelUserCodeParameterSupported: type: boolean description: 'The boolean flag which indicates whether the `user_code` request parameter is supported at the backchannel authentication endpoint. This property corresponds to the `backchannel_user_code_parameter_supported` metadata. ' backchannelBindingMessageRequiredInFapi: type: boolean description: 'The flag to indicate whether the `binding_message` request parameter is always required whenever a backchannel authentication request is judged as a request for Financial-grade API. ' x-mint: metadata: description: The flag to indicate whether the `binding_message` request parameter is always required whenever a backchannel authentication request is judged as a request for Financial-grade API. content: ' The FAPI-CIBA profile requires that the authorization server _"shall ensure unique authorization context exists in the authorization request or require a `binding_message` in the authorization request"_ (FAPI-CIBA, 5.2.2, 2). The simplest way to fulfill this requirement is to set this property to `true`. If this property is set to `false`, the `binding_message` request parameter remains optional even in FAPI context, but in exchange, your authorization server must implement a custom mechanism that ensures each backchannel authentication request has unique context. ' deviceAuthorizationEndpoint: type: string format: uri description: 'The URI of the device authorization endpoint. Device authorization endpoint is defined in the specification of OAuth 2.0 Device Authorization Grant. ' deviceVerificationUri: type: string format: uri description: 'The verification URI for the device flow. This URI is used as the value of the `verification_uri` parameter in responses from the device authorization endpoint. ' deviceVerificationUriComplete: type: string format: uri description: 'The verification URI for the device flow with a placeholder for a user code. This URI is used to build the value of the `verification_uri_complete` parameter in responses from the device authorization endpoint. ' x-mint: metadata: description: The verification URI for the device flow with a placeholder for a user code. This URI is used to build the value of the `verification_uri_complete` parameter in responses from the device authorization endpoint. content: ' It is expected that the URI contains a fixed string `USER_CODE` somewhere as a placeholder for a user code. For example, like the following. `https://example.com/device?user_code=USER_CODE` The fixed string is replaced with an actual user code when Authlete builds a verification URI with a user code for the `verification_uri_complete` parameter. If this URI is not set, the `verification_uri_complete` parameter won''t appear in device authorization responses. ' deviceFlowCodeDuration: type: integer format: int32 description: 'The duration of device verification codes and end-user verification codes issued from the device authorization endpoint in seconds. This is used as the value of the `expires_in` property in responses from the device authorization endpoint. ' deviceFlowPollingInterval: type: integer format: int32 description: 'The minimum interval between polling requests to the token endpoint from client applications in seconds in device flow. This is used as the value of the `interval` property in responses from the device authorization endpoint. ' userCodeCharset: $ref: '#/components/schemas/user_code_charset' userCodeLength: type: integer format: int32 description: 'The length of end-user verification codes (`user_code`) for Device Flow. ' supportedTrustFrameworks: type: array items: type: string description: 'Trust frameworks supported by this service. This corresponds to the `trust_frameworks_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). ' supportedEvidence: type: array items: type: string description: 'Evidence supported by this service. This corresponds to the `evidence_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). ' supportedIdentityDocuments: type: array items: type: string description: 'Identity documents supported by this service. This corresponds to the `id_documents_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). ' supportedVerificationMethods: type: array items: type: string description: 'Verification methods supported by this service. This corresponds to the `id_documents_verification_methods_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). ' supportedVerifiedClaims: type: array items: type: string description: 'Verified claims supported by this service. This corresponds to the `claims_in_verified_claims_supported` [metadata](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.7). ' verifiedClaimsValidationSchemaSet: $ref: '#/components/schemas/verified_claims_validation_schema' type: string description: 'OIDC4IDA / verifiedClaimsValidationSchemaSet ' attributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of this service. ' nbfOptional: type: boolean description: 'The flag indicating whether the nbf claim in the request object is optional even when the authorization request is regarded as a FAPI-Part2 request. ' x-mint: metadata: description: The flag indicating whether the nbf claim in the request object is optional even when the authorization request is regarded as a FAPI-Part2 request. content: ' The final version of Financial-grade API was approved in January, 2021. The Part 2 of the final version has new requirements on lifetime of request objects. They require that request objects contain an `nbf` claim and the lifetime computed by `exp` - `nbf` be no longer than 60 minutes. Therefore, when an authorization request is regarded as a FAPI-Part2 request, the request object used in the authorization request must contain an nbf claim. Otherwise, the authorization server rejects the authorization request. When this flag is `true`, the `nbf` claim is treated as an optional claim even when the authorization request is regarded as a FAPI-Part2 request. That is, the authorization server does not perform the validation on lifetime of the request object. Skipping the validation is a violation of the FAPI specification. The reason why this flag has been prepared nevertheless is that the new requirements (which do not exist in the Implementer''s Draft 2 released in October, 2018) have big impacts on deployed implementations of client applications and Authlete thinks there should be a mechanism whereby to make the migration from ID2 to Final smooth without breaking live systems. ' issSuppressed: type: boolean description: 'The flag indicating whether generation of the iss response parameter is suppressed. ' x-mint: metadata: description: The flag indicating whether generation of the iss response parameter is suppressed. content: ' "OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response" has defined a new authorization response parameter, `iss`, as a countermeasure for a certain type of mix-up attacks. The specification requires that the `iss` response parameter always be included in authorization responses unless JARM (JWT Secured Authorization Response Mode) is used. When this flag is `true`, the authorization server does not include the `iss` response parameter in authorization responses. By turning this flag on and off, developers of client applications can experiment the mix-up attack and the effect of the `iss` response parameter. Note that this flag should not be `true` in production environment unless there are special reasons for it. ' supportedCustomClientMetadata: type: array items: type: string description: 'custom client metadata supported by this service. ' x-mint: metadata: description: custom client metadata supported by this service. content: ' Standard specifications define client metadata as necessary. The following are such examples. * [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) * [RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591.html) * [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html) * [OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) * [The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-jwsreq/) * [Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html) * [OAuth 2.0 Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/rfc9126/) * [OAuth 2.0 Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/draft-ietf-oauth-rar/) Standard client metadata included in Client Registration Request and Client Update Request (cf. [OIDC DynReg](https://openid.net/specs/openid-connect-registration-1_0.html), [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html) and [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html)) are, if supported by Authlete, stored into Authlete database. On the other hand, unrecognized client metadata are discarded. By listing up custom client metadata in advance by using this property (`supportedCustomClientMetadata`), Authlete can recognize them and stores their values into the database. The stored custom client metadata values can be referenced by `customMetadata`. ' tokenExpirationLinked: type: boolean description: 'The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token. ' x-mint: metadata: description: The flag indicating whether the expiration date of an access token never exceeds that of the corresponding refresh token. content: ' When a new access token is issued by a refresh token request (= a token request with `grant_type=refresh_token`), the expiration date of the access token may exceed the expiration date of the corresponding refresh token. This behavior itself is not wrong and may happen when `refreshTokenKept` is `true` and/or when `refreshTokenDurationKept` is `true`. When this flag is `true`, the expiration date of an access token never exceeds that of the corresponding refresh token regardless of the calculated duration based on other settings such as `accessTokenDuration`, `accessTokenDuration` in `extension` and `access_token.duration` scope attribute. It is technically possible to set a value which is bigger than the duration of refresh tokens as the duration of access tokens although it is strange. In the case, the duration of an access token becomes longer than the duration of the refresh token which is issued together with the access token. Even if the duration values are configured so, if this flag is `true`, the expiration date of the access token does not exceed that of the refresh token. That is, the duration of the access token will be shortened, and as a result, the access token and the refresh token will have the same expiration date. ' frontChannelRequestObjectEncryptionRequired: type: boolean description: 'The flag indicating whether encryption of request object is required when the request object is passed through the front channel. ' x-mint: metadata: description: The flag indicating whether encryption of request object is required when the request object is passed through the front channel. content: ' This flag does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/). Unecrypted request objects are accepted at the endpoint even if this flag is `true`. This flag does not indicate whether a request object is always required. There is a different flag, `requestObjectRequired`, for the purpose. See the description of `requestObjectRequired` for details. Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` flag of the client is `true`. ' requestObjectEncryptionAlgMatchRequired: type: boolean description: 'The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata of the client that has sent the request object. ' x-mint: metadata: description: The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata of the client that has sent the request object. content: ' The request_object_encryption_alg client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_alg > > OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the OP that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects. The point here is "The RP MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present." The Client''s property that represents the client metadata is `requestEncryptionAlg`. See the description of `requestEncryptionAlg` for details. Even if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired` flag of the client is `true`. ' requestObjectEncryptionEncMatchRequired: type: boolean description: 'The flag indicating whether the JWE `enc` of encrypted request object must match the `request_object_encryption_enc` client metadata of the client that has sent the request object. ' x-mint: metadata: description: The flag indicating whether the JWE `enc` of encrypted request object must match the `request_object_encryption_enc` client metadata of the client that has sent the request object. content: ' The `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows. > request_object_encryption_enc > > OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request Objects sent to the OP. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided. The Client''s property that represents the client metadata is `requestEncryptionEnc`. See the description of `requestEncryptionEnc` for details. Even if this flag is false, the match is required if the `requestObjectEncryptionEncMatchRequired` flag is `true`. ' hsmEnabled: type: boolean description: 'The flag indicating whether HSM (Hardware Security Module) support is enabled for this service. When this flag is `false`, keys managed in HSMs are not used even if they exist. In addition, `/api/hsk/*` APIs reject all requests. Even if this flag is `true`, HSM-related features do not work if the configuration of the Authlete server you are using does not support HSM. ' hsks: type: array items: $ref: '#/components/schemas/hsk' description: 'The information about keys managed on HSMs (Hardware Security Modules). This `hsks` property is output only, meaning that `hsks` in requests to `/api/service/create` API and `/api/service/update` API do not have any effect. The contents of this property is controlled only by `/api/hsk/*` APIs. ' grantManagementEndpoint: type: string description: 'The URL of the grant management endpoint. ' grantManagementActionRequired: type: boolean description: 'The flag indicating whether every authorization request (and any request serving as an authorization request such as CIBA backchannel authentication request and device authorization request) must include the `grant_management_action` request parameter. ' x-mint: metadata: description: The flag indicating whether every authorization request (and any request serving as an authorization request such as CIBA backchannel authentication request and device authorization request) must include the `grant_management_action` request parameter. content: ' This property corresponds to the `grant_management_action_required` server metadata defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). Note that setting true to this property will result in blocking all public clients because the specification requires that grant management be usable only by confidential clients for security reasons. ' unauthorizedOnClientConfigSupported: type: boolean description: 'The flag indicating whether Authlete''s `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate. ' x-mint: metadata: description: The flag indicating whether Authlete's `/api/client/registration` API uses `UNAUTHORIZED` as a value of the `action` response parameter when appropriate. content: ' The `UNAUTHORIZED` enum value was initially not defined as a possible value of the `action` parameter in an `/api/client/registration` API response. This means that implementations of client `configuration` endpoint were not able to conform to [RFC 7592](https://www.rfc-editor.org/rfc/rfc7592.html) strictly. For backward compatibility (to avoid breaking running systems), Authlete''s `/api/client/registration` API does not return the `UNAUTHORIZED` enum value if this flag is not turned on. The steps an existing implementation of client configuration endpoint has to do in order to conform to the requirement related to "401 Unauthorized" are as follows. 1. Update the Authlete library (e.g. authlete-java-common) your system is using. 2. Update your implementation of client configuration endpoint so that it can handle the `UNAUTHORIZED` action. 3. Turn on this `unauthorizedOnClientConfigSupported` flag. ' dcrScopeUsedAsRequestable: type: boolean description: 'The flag indicating whether the `scope` request parameter in dynamic client registration and update requests (RFC 7591 and RFC 7592) is used as scopes that the client can request. Limiting the range of scopes that a client can request is achieved by listing scopes in the `client.extension.requestableScopes` property and setting the `client.extension.requestableScopesEnabled` property to `true`. This feature is called "requestable scopes". This property affects behaviors of `/api/client/registration` and other family APIs. ' endSessionEndpoint: type: string format: uri description: 'The endpoint for clients ending the sessions. A URL that starts with `https://` and has no fragment component. For example, `https://example.com/auth/endSession`. The value of this property is used as `end_session_endpoint` property in the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). ' loopbackRedirectionUriVariable: type: boolean description: 'The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback. ' x-mint: metadata: description: The flag indicating whether the port number component of redirection URIs can be variable when the host component indicates loopback. content: ' When this flag is `true`, if the host component of a redirection URI specified in an authorization request indicates loopback (to be precise, when the host component is localhost, `127.0.0.1` or `::1`), the port number component is ignored when the specified redirection URI is compared to pre-registered ones. This behavior is described in [7.3. Loopback Interface Redirection]( https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3) of [RFC 8252 OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html) for Native Apps. [3.1.2.3. Dynamic Configuration](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1.2.3) of [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html) states _"If the client registration included the full redirection URI, the authorization server MUST compare the two URIs using simple string comparison as defined in [RFC3986] Section 6.2.1."_ Also, the description of `redirect_uri` in [3.1.2.1. Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) states _"This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider, with the matching performed as described in Section 6.2.1 of [RFC3986] (**Simple String Comparison**)."_ These "Simple String Comparison" requirements are preceded by this flag. That is, even when the conditions described in RFC 6749 and OpenID Connect Core 1.0 are satisfied, the port number component of loopback redirection URIs can be variable when this flag is `true`. [8.3. Loopback Redirect Considerations](https://www.rfc-editor.org/rfc/rfc8252.html#section-8.3) of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) states as follows. > While redirect URIs using localhost (i.e., `"http://localhost:{port}/{path}"`) function similarly to loopback IP redirects described in Section 7.3, the use of localhost is NOT RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather than localhost avoids inadvertently listening on network interfaces other than the loopback interface. It is also less susceptible to client-side firewalls and misconfigured host name resolution on the user''s device. However, Authlete allows the port number component to be variable in the case of `localhost`, too. It is left to client applications whether they use `localhost` or a literal loopback IP address (`127.0.0.1` for IPv4 or `::1` for IPv6). Section 7.3 and Section 8.3 of [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html) state that loopback redirection URIs use the `"http"` scheme, but Authlete allows the port number component to be variable in other cases (e.g. in the case of the `"https"` scheme), too. ' requestObjectAudienceChecked: type: boolean description: 'The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service. ' x-mint: metadata: description: The flag indicating whether Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service. content: ' [Section 6.1. Passing a Request Object by Value](https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests) of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) has the following statement. > The `aud` value SHOULD be or include the OP''s Issuer Identifier URL. Likewise, [Section 4. Request Object](https://www.rfc-editor.org/rfc/rfc9101.html#section-4) of [RFC 9101](https://www.rfc-editor.org/rfc/rfc9101.html) (The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)) has the following statement. > The value of aud should be the value of the authorization server (AS) issuer, as defined in [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html). As excerpted above, validation on the `aud` claim of request objects is optional. However, if this flag is turned on, Authlete checks whether the `aud` claim of request objects matches the issuer identifier of this service and raises an error if they are different. ' accessTokenForExternalAttachmentEmbedded: type: boolean description: 'The flag indicating whether Authlete generates access tokens for external attachments and embeds them in ID tokens and userinfo responses. ' authorityHints: type: array items: type: string description: 'Identifiers of entities that can issue entity statements for this service. This property corresponds to the `authority_hints` property that appears in a self-signed entity statement that is defined in OpenID Connect Federation 1.0. ' federationEnabled: type: boolean description: 'flag indicating whether this service supports OpenID Connect Federation 1 ' federationJwks: type: string description: 'JWK Set document containing keys that are used to sign (1) self-signed entity statement of this service and (2) the response from `signed_jwks_uri`. ' federationSignatureKeyId: type: string description: 'A key ID to identify a JWK used to sign the entity configuration and the signed JWK Set. ' federationConfigurationDuration: type: integer description: 'The duration of the entity configuration in seconds. ' federationRegistrationEndpoint: type: string description: 'The URI of the federation registration endpoint. This property corresponds to the `federation_registration_endpoint` server metadata that is defined in OpenID Connect Federation 1.0. ' organizationName: type: string description: 'The human-readable name representing the organization that operates this service. This property corresponds to the `organization_name` server metadata that is defined in OpenID Connect Federation 1.0. ' predefinedTransformedClaims: type: string description: 'The transformed claims predefined by this service in JSON format. This property corresponds to the `transformed_claims_predefined` server metadata. ' refreshTokenIdempotent: type: boolean description: 'flag indicating whether refresh token requests with the same refresh token can be made multiple times in quick succession and they can obtain the same renewed refresh token within the short period. ' signedJwksUri: type: string description: 'The URI of the endpoint that returns this service''s JWK Set document in the JWT format. This property corresponds to the `signed_jwks_uri` server metadata defined in OpenID Connect Federation 1.0. ' supportedAttachments: type: array items: $ref: '#/components/schemas/attachment_type' description: 'Supported attachment types. This property corresponds to the {@code attachments_supported} server metadata which was added by the third implementer''s draft of OpenID Connect for Identity Assurance 1.0. ' supportedDigestAlgorithms: type: array items: type: string description: 'Supported algorithms used to compute digest values of external attachments. This property corresponds to the `digest_algorithms_supported` server metadata which was added by the third implementer''s draft of OpenID Connect for Identity Assurance 1.0. ' supportedDocuments: type: array items: type: string description: 'Document types supported by this service. This property corresponds to the `documents_supported` server metadata. ' supportedDocumentsMethods: type: array items: type: string description: 'validation and verification processes supported by this service. This property corresponds to the `documents_methods_supported` server metadata. The third implementer''s draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) renamed the `id_documents_verification_methods_supported` server metadata to `documents_methods_supported`. ' supportedDocumentsValidationMethods: type: array items: type: string description: 'Document validation methods supported by this service. This property corresponds to the `documents_validation_methods_supported` server metadata which was added by the third implementer''s draft of ' supportedDocumentsVerificationMethods: type: array items: type: string description: 'Document verification methods supported by this service. This property corresponds to the `documents_verification_methods_supported` server metadata which was added by the third implementer''s draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) ' supportedElectronicRecords: type: array items: type: string description: 'Electronic record types supported by this service. This property corresponds to the `electronic_records_supported` server metadata which was added by the third implementer''s draft of [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html) ' supportedClientRegistrationTypes: type: array items: $ref: '#/components/schemas/client_registration_type' tokenExchangeByIdentifiableClientsOnly: type: boolean description: 'The flag indicating whether to prohibit unidentifiable clients from making token exchange requests. ' tokenExchangeByConfidentialClientsOnly: type: boolean description: 'The flag indicating whether to prohibit public clients from making token exchange requests. ' tokenExchangeByPermittedClientsOnly: type: boolean description: 'The flag indicating whether to prohibit clients that have no explicit permission from making token exchange requests. ' tokenExchangeEncryptedJwtRejected: type: boolean description: 'The flag indicating whether to reject token exchange requests which use encrypted JWTs as input tokens. ' tokenExchangeUnsignedJwtRejected: type: boolean description: 'The flag indicating whether to reject token exchange requests which use unsigned JWTs as input tokens. ' jwtGrantByIdentifiableClientsOnly: type: boolean description: 'The flag indicating whether to prohibit unidentifiable clients from using the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". ' jwtGrantEncryptedJwtRejected: type: boolean description: 'The flag indicating whether to reject token requests that use an encrypted JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". ' jwtGrantUnsignedJwtRejected: type: boolean description: 'The flag indicating whether to reject token requests that use an unsigned JWT as an authorization grant with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer". ' dcrDuplicateSoftwareIdBlocked: type: boolean description: 'The flag indicating whether to block DCR (Dynamic Client Registration) requests whose "software_id" has already been used previously. ' trustAnchors: type: array items: $ref: '#/components/schemas/trust_anchor' description: 'The trust anchors that are referenced when this service resolves trust chains of relying parties. If this property is empty, client registration fails regardless of whether its type is `automatic` or `explicit`. It means that OpenID Connect Federation 1.0 does not work. ' openidDroppedOnRefreshWithoutOfflineAccess: type: boolean description: 'The flag indicating whether the openid scope should be dropped from scopes list assigned to access token issued when a refresh token grant is used. ' supportedDocumentsCheckMethods: type: array items: type: string description: 'Supported document check methods. This property corresponds to the `documents_check_methods_supported` server metadata which was added by the fourth implementer''s draft of OpenID Connect for Identity Assurance 1.0. ' rsResponseSigned: type: boolean description: 'The flag indicating whether this service signs responses from the resource server. ' cnonceDuration: type: integer format: int64 description: 'The duration of `c_nonce`. ' dpopNonceRequired: type: boolean description: 'Whether to require DPoP proof JWTs to include the `nonce` claim whenever they are presented. ' verifiableCredentialsEnabled: type: boolean description: 'Get the flag indicating whether the feature of Verifiable Credentials for this service is enabled or not. ' credentialJwksUri: type: string description: 'The URL at which the JWK Set document of the credential issuer is exposed. ' credentialOfferDuration: type: integer format: int64 description: 'The default duration of credential offers in seconds. ' dpopNonceDuration: type: integer format: int64 description: 'The duration of nonce values for DPoP proof JWTs in seconds. ' preAuthorizedGrantAnonymousAccessSupported: type: boolean description: 'The flag indicating whether token requests using the pre-authorized code grant flow by unidentifiable clients are allowed. ' credentialTransactionDuration: type: integer format: int64 description: 'The duration of transaction ID in seconds that may be issued as a result of a credential request or a batch credential request. ' introspectionSignatureKeyId: type: string description: 'The key ID of the key for signing introspection responses. ' resourceSignatureKeyId: type: string description: 'The key ID of the key for signing introspection responses. ' userPinLength: type: integer format: int32 description: 'The default length of user PINs. ' supportedPromptValues: type: array items: $ref: '#/components/schemas/prompt' description: 'The supported `prompt` values. ' idTokenReissuable: type: boolean description: 'The flag indicating whether to enable the feature of ID token reissuance in the refresh token flow. ' credentialJwks: type: string description: 'The JWK Set document containing private keys that are used to sign verifiable credentials. ' fapiModes: type: array items: $ref: '#/components/schemas/fapi_mode' description: 'FAPI modes for this service. When the value of this property is not `null`, Authlete always processes requests to this service based on the specified FAPI modes if the FAPI feature is enabled in Authlete and the FAPI profile is supported by this service. For instance, when this property is set to an array containing `FAPI1_ADVANCED` only, Authlete always processes requests to this service based on "Financial-grade API Security Profile 1.0 - Part 2: Advanced" if the FAPI feature is enabled in Authlete and the FAPI profile is supported by this service. ' credentialDuration: type: integer format: int64 description: 'The default duration of verifiable credentials in seconds. ' credentialIssuerMetadata: $ref: '#/components/schemas/credential_issuer_metadata' idTokenAudType: type: string description: 'The type of the `aud` claim in ID tokens. ' nativeSsoSupported: type: boolean description: 'Flag that enables the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (“Native SSO”). When this property is **not** `true`, Native SSO specific parameters are ignored or treated as errors. For example: * The `device_sso` scope has no special meaning (Authlete does not embed the `sid` claim in ID tokens). * The `urn:openid:params:token-type:device-secret` token type is treated as unknown and results in an error. When set to `true`, the server metadata advertises `"native_sso_supported": true`. See [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) and [RFC 8414 §2](https://www.rfc-editor.org/rfc/rfc8414.html#section-2) for background. Native SSO is available in Authlete 3.0 and later. ' oid4vciVersion: type: string description: 'Version of the [OpenID for Verifiable Credential Issuance](https://www.authlete.com/developers/oid4vci/) (OID4VCI) specification to support. Accepted values are: * `null` or `"1.0-ID1"` → Implementer’s Draft 1. * `"1.0"` or `"1.0-Final"` → Final 1.0 specification. Choose the value that matches the OID4VCI behaviour your service should expose. See the OID4VCI documentation for details. ' cimdMetadataPolicyEnabled: type: boolean description: 'Flag that controls whether the CIMD metadata policy is applied to client metadata obtained through the Client ID Metadata Document (CIMD) mechanism. ' clientIdMetadataDocumentSupported: type: boolean description: 'Indicates whether the Client ID Metadata Document (CIMD) mechanism is supported. When `true`, the service will attempt to retrieve client metadata via CIMD where applicable. ' cimdAllowlistEnabled: type: boolean description: 'Enables the allowlist for CIMD. When `true`, only CIMD endpoints that are on the allowlist are used. ' cimdAllowlist: type: array items: type: string description: 'The allowlist of CIMD endpoints (hosts/URIs) that may be used when retrieving client metadata via Client ID Metadata Documents. ' cimdAlwaysRetrieved: type: boolean description: 'If `true`, CIMD retrieval is always attempted for clients, regardless of other conditions. ' cimdHttpPermitted: type: boolean description: 'Allows CIMD retrieval over plain HTTP. When `false`, only HTTPS CIMD endpoints are allowed. ' cimdQueryPermitted: type: boolean description: 'Allows the use of query parameters when retrieving CIMD metadata. When `false`, query parameters are disallowed for CIMD requests. ' cimdMetadataPolicy: type: string description: 'The metadata policy applied to client metadata obtained through the CIMD mechanism. The value must follow the metadata policy grammar defined in [OpenID Federation 1.0 §6.1 Metadata Policy](https://openid.net/specs/openid-federation-1_0.html#name-metadata-policy). ' httpAliasProhibited: type: boolean description: 'When `true`, client ID aliases starting with `https://` or `http://` are prohibited. ' attestationChallengeTimeWindow: type: integer format: int64 description: 'The time window of attestation challenges in seconds. This is used for OAuth 2.0 Attestation-Based Client Authentication. ' claim_type: type: string enum: - NORMAL - AGGREGATED - DISTRIBUTED 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. ' client_type: type: string description: 'The client type, either `CONFIDENTIAL` or `PUBLIC`. See [RFC 6749, 2.1. Client Types](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) for details. ' enum: - PUBLIC - CONFIDENTIAL service_profile: type: string enum: - FAPI - OPEN_BANKING 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. delivery_mode: type: string enum: - PING - POLL - PUSH 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' client_limited_authorization: type: object properties: number: type: integer format: int32 readOnly: true description: 'The sequential number of the client. The value of this property is assigned by Authlete. ' clientName: type: string description: 'The name of the client application. This property corresponds to `client_name` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' clientNames: type: array items: $ref: '#/components/schemas/tagged_value' description: 'Client names with language tags. If the client application has different names for different languages, this property can be used to register the names. ' description: type: string description: The description about the client application. descriptions: type: array items: $ref: '#/components/schemas/tagged_value' description: 'Descriptions about the client application with language tags. If the client application has different descriptions for different languages, this property can be used to register the descriptions. ' clientId: type: integer format: int64 readOnly: true description: The client identifier used in Authlete API calls. The value of this property is assigned by Authlete. clientIdAlias: type: string description: 'The value of the client''s `client_id` property used in OAuth and OpenID Connect calls. By default, this is a string version of the `clientId` property. ' clientIdAliasEnabled: type: boolean description: Deprecated. Always set to `true`. clientType: $ref: '#/components/schemas/client_type' logoUri: type: string description: 'The URL pointing to the logo image of the client application. This property corresponds to `logo_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' logoUris: type: array items: $ref: '#/components/schemas/tagged_value' description: 'Logo image URLs with language tags. If the client application has different logo images for different languages, this property can be used to register URLs of the images. ' tosUri: type: string description: 'The URL pointing to the "Terms Of Service" page. This property corresponds to `tos_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' tosUris: type: array items: $ref: '#/components/schemas/tagged_value' description: 'URLs of "Terms Of Service" pages with language tags. If the client application has different "Terms Of Service" pages for different languages, this property can be used to register the URLs. ' policyUri: type: string description: 'The URL pointing to the page which describes the policy as to how end-user''s profile data is used. This property corresponds to `policy_uri` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' policyUris: type: array items: $ref: '#/components/schemas/tagged_value' description: 'URLs of policy pages with language tags. If the client application has different policy pages for different languages, this property can be used to register the URLs. ' serviceNumber: type: integer format: int32 readOnly: true description: 'The sequential number of the service of the client application. The value of this property is assigned by Authlete. ' defaultMaxAge: type: integer format: int32 description: 'The default maximum authentication age in seconds. This value is used when an authorization request from the client application does not have `max_age` request parameter. This property corresponds to `default_max_age` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' authTimeRequired: type: boolean description: 'The flag to indicate whether this client requires `auth_time` claim to be embedded in the ID token. This property corresponds to `require_auth_time` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' createdAt: type: integer format: int64 readOnly: true description: The time at which this client was created. The value is represented as milliseconds since the UNIX epoch (1970-01-01). modifiedAt: type: integer format: int64 readOnly: true description: The time at which this client was last modified. The value is represented as milliseconds since the UNIX epoch (1970-01-01). tlsClientCertificateBoundAccessTokens: type: boolean description: 'The flag to indicate whether this client use TLS client certificate bound access tokens. ' bcUserCodeRequired: type: boolean description: 'The boolean flag to indicate whether a user code is required when this client makes a backchannel authentication request. This property corresponds to the `backchannel_user_code_parameter` metadata. ' dynamicallyRegistered: type: boolean readOnly: true description: 'The flag to indicate whether this client has been registered dynamically. For more details, see [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). ' parRequired: type: boolean description: 'The flag to indicate whether this client is required to use the pushed authorization request endpoint. This property corresponds to the `require_pushed_authorization_requests` client metadata defined in "OAuth 2.0 Pushed Authorization Requests". ' requestObjectRequired: type: boolean description: 'The flag to indicate whether authorization requests from this client are always required to utilize a request object by using either `request` or `request_uri` request parameter. If this flag is set to `true` and the service''s `traditionalRequestObjectProcessingApplied` is set to `false`, authorization requests from this client are processed as if `require_signed_request_object` client metadata of this client is `true`. The metadata is defined in "JAR (JWT Secured Authorization Request)". ' frontChannelRequestObjectEncryptionRequired: type: boolean description: 'The flag indicating whether encryption of request object is required when the request object is passed through the front channel. ' x-mint: metadata: description: The flag indicating whether encryption of request object is required when the request object is passed through the front channel. content: ' This flag does not affect the processing of request objects at the Pushed Authorization Request Endpoint, which is defined in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/rfc9126/). Unecrypted request objects are accepted at the endpoint even if this flag is `true`. This flag does not indicate whether a request object is always required. There is a different flag, `requestObjectRequired`, for the purpose. Even if this flag is `false`, encryption of request object is required if the `frontChannelRequestObjectEncryptionRequired` flag of the service is `true`. ' requestObjectEncryptionAlgMatchRequired: type: boolean description: 'The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata. ' x-mint: metadata: description: The flag indicating whether the JWE alg of encrypted request object must match the `request_object_encryption_alg` client metadata. content: "\nThe `request_object_encryption_alg` client metadata itself is defined in [OpenID Connect Dynamic\nClient Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.\n\n> request_object_encryption_alg\n>\n> OPTIONAL. JWE [JWE] alg algorithm [JWA] the RP is declaring that it may use for encrypting Request\n Objects sent to the OP. This parameter SHOULD be included when symmetric encryption will be used,\n since this signals to the OP that a client_secret value needs to be returned from which the\n symmetric key will be derived, that might not otherwise be returned. The RP MAY still use other\n supported encryption algorithms or send unencrypted Request Objects, even when this parameter\n is present. If both signing and encryption are requested, the Request Object will be signed\n then encrypted, with the result being a Nested JWT, as defined in [JWT]. The default, if omitted,\n is that the RP is not declaring whether it might encrypt any Request Objects.\n\nThe point here is \"The RP MAY still use other supported encryption algorithms or send unencrypted\nRequest Objects, even when this parameter is present.\"\n\nThe property that represents the client metadata is `requestEncryptionAlg`. See the description\nof `requestEncryptionAlg` for details.\n\nEven if this flag is `false`, the match is required if the `requestObjectEncryptionAlgMatchRequired`\nflag of the service is `true`.\n\n" requestObjectEncryptionEncMatchRequired: type: boolean description: 'The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata. ' x-mint: metadata: description: The flag indicating whether the JWE enc of encrypted request object must match the `request_object_encryption_enc` client metadata. content: "\nThe `request_object_encryption_enc` client metadata itself is defined in [OpenID Connect Dynamic\nClient Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) as follows.\n\n> request_object_encryption_enc\n>\n> OPTIONAL. JWE enc algorithm [JWA] the RP is declaring that it may use for encrypting Request\n Objects sent to the OP. If request_object_encryption_alg is specified, the default for this\n value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg\n MUST also be provided.\n\nThe property that represents the client metadata is `requestEncryptionEnc`. See the description\nof `requestEncryptionEnc` for details.\n\nEven if this flag is `false`, the match is required if the `requestObjectEncryptionEncMatchRequired`\nflag of the service is `true`.\n\n" singleAccessTokenPerSubject: type: boolean description: 'If `Enabled` is selected, an attempt to issue a new access token invalidates existing access tokens that are associated with the same combination of subject and client. Note that, however, attempts by Client Credentials Flow do not invalidate existing access tokens because access tokens issued by Client Credentials Flow are not associated with any end-user''s subject. Even if `Disabled` is selected here, single access token per subject is effective if `singleAccessTokenPerSubject` of the `Service` this client belongs to is Enabled. ' pkceRequired: type: boolean description: 'The flag to indicate whether the use of Proof Key for Code Exchange (PKCE) is always required for authorization requests by Authorization Code Flow. If `true`, `code_challenge` request parameter is always required for authorization requests using Authorization Code Flow. See [RFC 7636](https://tools.ietf.org/html/rfc7636) (Proof Key for Code Exchange by OAuth Public Clients) for details about `code_challenge` request parameter. ' pkceS256Required: type: boolean description: 'The flag to indicate whether `S256` is always required as the code challenge method whenever [PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636) is used. If this flag is set to `true`, `code_challenge_method=S256` must be included in the authorization request whenever it includes the `code_challenge` request parameter. Neither omission of the `code_challenge_method` request parameter nor use of plain (`code_challenge_method=plain`) is allowed. ' rsRequestSigned: type: boolean description: 'The flag indicating whether this service signs responses from the resource server. ' dpopRequired: type: boolean description: 'If the DPoP is required for this client ' locked: type: boolean description: 'The flag which indicates whether this client is locked. ' mtlsEndpointAliasesUsed: type: boolean description: 'The flag indicating whether the client intends to prefer mutual TLS endpoints over non-MTLS endpoints. This property corresponds to the `use_mtls_endpoint_aliases` client metadata that is defined in [FAPI 2.0 Security Profile, 8.1.1. use_mtls_endpoint_aliases](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-8.1.1). ' inScopeForTokenMigration: type: boolean description: "The flag indicating whether this client is in scope for token migration \noperations.\n" trustChainExpiresAt: type: integer format: int64 description: 'the expiration time of the trust chain that was used when this client was registered or updated by the mechanism defined in OpenID Connect Federation 1.0. The value is represented as milliseconds elapsed since the Unix epoch (1970-01-01). ' trustChainUpdatedAt: type: integer format: int64 description: 'the time at which the trust chain was updated by the mechanism defined in OpenID Connect Federation 1.0 ' automaticallyRegistered: type: boolean description: 'The flag indicating whether this client was registered by the "automatic" client registration of OIDC Federation. ' explicitlyRegistered: type: boolean description: 'The flag indicating whether this client was registered by the "explicit" client registration of OIDC Federation. ' credentialResponseEncryptionRequired: type: boolean description: True if credential responses to this client must be always encrypted. metadataDocumentLocation: type: string format: uri description: 'Location of the Client ID Metadata Document that was used for this client. This property is set when client metadata was retrieved via the OAuth Client ID Metadata Document (CIMD) mechanism. ' metadataDocumentExpiresAt: type: integer format: int64 description: 'Expiration time of the metadata document (UNIX time in milliseconds). ' metadataDocumentUpdatedAt: type: integer format: int64 description: 'Last-updated time of the metadata document (UNIX time in milliseconds). ' discoveredByMetadataDocument: type: boolean description: 'Indicates whether this client was discovered via a Client ID Metadata Document. ' clientSource: type: string description: 'Source of this client record. ' enum: - DYNAMIC_REGISTRATION - AUTOMATIC_REGISTRATION - EXPLICIT_REGISTRATION - METADATA_DOCUMENT - STATIC_REGISTRATION entityId: type: string description: 'the entity ID of this client. ' credential_offer_info: type: object properties: identifier: type: string description: The identifier of the credential offer. credentialOffer: type: string description: The credential offer in the JSON format. credentialIssuer: type: string description: The identifier of the credential issuer. authorizationCodeGrantIncluded: type: boolean description: 'The flag indicating whether the `authorization_code` object is included in the `grants` object. ' issuerStateIncluded: type: boolean description: 'The flag indicating whether the `issuer_state` property is included in the `authorization_code` object in the `grants` object. ' issuerState: type: string description: 'The value of the `issuer_state` property in the `authorization_code` object in the `grants` object. ' preAuthorizedCodeGrantIncluded: type: boolean description: 'The flag indicating whether the `urn:ietf:params:oauth:grant-type:pre-authorized_code` object is included in the `grants` object. ' preAuthorizedCode: type: string description: 'The value of the `pre-authorized_code` property in the `urn:ietf:params:oauth:grant-type:pre-authorized_code` object in the `grants` object. ' subject: type: string description: The subject associated with the credential offer. expiresAt: type: integer format: int64 description: The time at which the credential offer will expire. context: type: string description: The general-purpose arbitrary string. properties: type: array items: $ref: '#/components/schemas/property' description: Extra properties to associate with the credential offer. jwtAtClaims: type: string description: 'Additional claims that are added to the payload part of the JWT access token. ' authTime: type: integer format: int64 description: 'The time at which the user authentication was performed during the course of issuing the credential offer. ' acr: type: string description: 'The Authentication Context Class Reference of the user authentication performed during the course of issuing the credential offer. ' credentialConfigurationIds: type: array items: type: string description: 'The value of the `credential_configuration_ids` property of the credential offer. ' x-mint: metadata: description: The value of the `credential_configuration_ids` property of the credential offer. content: "\n```\n{\n \"credential_issuer\": \"...\",\n \"credential_configuration_ids\": [ ... ],\n \"grants\": { ... }\n}\n```\n\n" txCode: type: string description: 'The transaction code. ' txCodeInputMode: type: string description: 'The input mode of the transaction code. ' txCodeDescription: type: string description: 'The description of the transaction code. ' client_auth_method: type: string description: 'The client authentication method that the client application declares that it uses at the token endpoint. This property corresponds to `token_endpoint_auth_method` in [OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata). ' enum: - NONE - CLIENT_SECRET_BASIC - CLIENT_SECRET_POST - CLIENT_SECRET_JWT - PRIVATE_KEY_JWT - TLS_CLIENT_AUTH - SELF_SIGNED_TLS_CLIENT_AUTH - ATTEST_JWT_CLIENT_AUTH 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`). ' user_code_charset: type: string description: 'The character set for end-user verification codes (`user_code`) for Device Flow. ' enum: - BASE20 - NUMERIC 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' named_uri: type: object properties: name: type: string uri: type: string format: uri dynamic_scope: type: object properties: name: type: string description: The scope name. value: type: string description: The scope value. authorization_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 - LOCATION - FORM 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. ' accessToken: type: string description: 'The newly issued access token. Note that an access token is issued from an authorization endpoint only when `response_type` contains token. ' accessTokenExpiresAt: type: integer format: int64 description: 'The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). ' accessTokenDuration: type: integer format: int64 description: 'The duration of the newly issued access token in seconds. ' idToken: type: string description: 'The newly issued ID token. Note that an ID token is issued from an authorization endpoint only when `response_type` contains `id_token`. ' authorizationCode: type: string description: 'The newly issued authorization code. Note that an authorization code is issued only when `response_type` contains code. ' jwtAccessToken: type: string description: 'The newly issued access token in JWT format. If the service is not configured to issue JWT-based access tokens, this property is always set to `null`. ' ticketInfo: $ref: '#/components/schemas/authorization_ticket_info' description: 'The information about the ticket. ' verified_claims_validation_schema: type: string description: 'The verified claims validation schema set. ' enum: - standard - standard+id_document responses: '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.' '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.' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' links: token_exchange: operationId: auth_token_api parameters: serviceId: $request.path.serviceId authz_fail: operationId: auth_authorization_fail_api parameters: serviceId: $request.path.serviceId ticket: $response.body#/ticket authz_issue: operationId: auth_authorization_issue_api parameters: serviceId: $request.path.serviceId ticket: $response.body#/ticket token_issue_direct: operationId: auth_token_issue_api parameters: serviceId: $request.path.serviceId 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. '