> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Process Authorization Request
> This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further.
This API is supposed to be called from within the implementation of the authorization endpoint of
the service. The endpoint implementation must extract the request parameters from the authorization
request from the client application and pass them as the value of parameters request parameter for
Authlete's `/auth/authorization` API.
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`.
The following code snippet is an example in JAX-RS showing how to extract request parameters from
the authorization request.
```java
@GET
public Response get(@Context UriInfo uriInfo)
{
// The query parameters of the authorization request.
String parameters = uriInfo.getRequestUri().getQuery();
......
}
@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response post(String parameters)
{
// 'parameters' is the entity body of the authorization request.
......
}
```
The endpoint implementation does not have to parse the request parameters from the client application
because Authlete's `/auth/authorization` API does it.
The response from `/auth/authorization` API has various parameters. Among them, it is `action`
parameter that the authorization server implementation should check first because it denotes the
next action that the authorization server implementation should take. According to the value of
`action`, the service implementation must take the steps described below.
## INTERNAL\_SERVER\_ERROR
When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization
server implementation was wrong or that an error occurred in Authlete.
In either case, from the viewpoint of the client application, it is an error on the server side.
Therefore, the service implementation should generate a response to the client application with
HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
type although OAuth 2.0 specification does not mention the format of the error response when the
redirect URI is not usable.
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 request from the client application
is invalid.
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 although OAuth 2.0 specification does
not mention the format of the error response when the redirect URI is not usable.
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 request from the client application
is invalid but the redirect URI
to which the error should be reported has been determined.
A response with HTTP status of "302 Found" must be returned to the client application with `Location`
header which has a redirect URI with error parameter.
The value of `responseContent` is a redirect URI with `error` parameter, 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 request from the client application is
invalid but the redirect URI to which the error should be reported has been determined, and that
the authorization request contains `response_mode=form_post` as is defined in [OAuth 2.0 Form Post
Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html).
The HTTP status of the response returned to the client application should be "200 OK" and the
content type should be `text/html;charset=UTF-8`.
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}
```
## NO\_INTERACTION
When the value of `action` is `NO_INTERACTION`, it means that the request from the client application
has no problem and requires the service to process the request without displaying any user interface
pages for authentication or consent. This case happens when the authorization request contains
`prompt=none`.
The service must follow the steps described below.
**\[1] END-USER AUTHENTICATION**
Check whether an end-user has already logged in. If an end-user has logged in, go to the next step (\[MAX\_AGE]).
Otherwise, call Authlete's `/auth/authorization/fail` API with `reason=NOT_LOGGED_IN` and use the response from
the API to generate a response to the client application.
**\[2] MAX AGE**
Get the value of `maxAge` parameter from the `/auth/authorization` API response. The value represents
the maximum authentication age which has come from `max_age` request parameter or `defaultMaxAge`
configuration parameter of the client application. If the value is `0`, go to the next step (\[SUBJECT]).
Otherwise, follow the sub steps described below.
* (i) Get the time at which the end-user was authenticated. Note that this value is not managed by Authlete,
meaning that it is expected that the service implementation manages the value. If the service implementation
does not manage authentication time of end-users, call Authlete's `/auth/authorization/fail` API
with `reason=MAX_AGE_NOT_SUPPORTED` and use the API response to generate a response to the client
application.
* (ii) Add the value of the maximum authentication age (which is represented in seconds) to the authentication
time. The calculated value is the expiration time.
* (iii) Check whether the calculated value is equal to or greater than the current time. If this condition
is satisfied, go to the next step (\[SUBJECT]). Otherwise, call Authlete's `/auth/authorization/fail`
API with `reason=EXCEEDS_MAX_AGE` and use the API response to generate a response to the client
application.
**\[3] SUBJECT**
Get the value of `subject` from the `/auth/authorization` API response. The value represents an
end-user who the client application expects to grant authorization. If the value is `null`, go to
the next step (\[ACRs]). Otherwise, follow the sub steps described below.
* (i) Compare the value of the requested subject to the current end-user.
* (ii) If they are equal, go to the next step (\[ACRs]). If they are not equal, call Authlete's
`/auth/authorization/fail` API with `reason=DIFFERENT_SUBJECT` and use the response from the API
to generate a response to the client application.
**\[4] ACRs**
Get the value of `acrs` from the `/auth/authorization` API response. The value represents a list
of ACRs (Authentication Context Class References) and comes from (1) acr claim in `claims` request
parameter, (2) `acr_values` request parameter, or (3) `default_acr_values` configuration parameter
of the client application.
It is ensured that all the ACRs in acrs are supported by the authorization server implementation.
In other words, it is ensured that all the ACRs are listed in `acr_values_supported` configuration
parameter of the authorization server.
If the value of ACRs is `null`, go to the next step (\[ISSUE]). Otherwise, follow the sub steps
described below.
* (i) Get the ACR performed for the authentication of the current end-user. Note that this value is
managed not by Authlete but by the authorization server implementation. (If the authorization server
implementation cannot handle ACRs, it should not have listed ACRs as `acr_values_supported`.)
* (ii) Compare the ACR value obtained in the above step to each element in the ACR array (`acrs`)
in the listed order.
* (iii) If the ACR value was found in the array, (= the ACR performed for the authentication of the
current end-user did not match any one of the ACRs requested by the client application), check
whether one of the requested ACRs must be satisfied or not using `acrEssential` parameter in the
`/auth/authorization` API response. If the value of `acrEssential` parameter is `true`, call Authlete's
`/auth/authorization/fail` API with `reason=ACR_NOT_SATISFIED` and use the response from the API
to generate a response to the client application. Otherwise, go to the next step (\[SCOPES]).
**\[5] SCOPES**
Get the value of `scopes` from the `/auth/authorization` API response. If the array contains a
scope which has not been granted to the client application by the end-user in the past, call
Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from
the API to generate a response to the client application. Otherwise, go to the next step (\[RESOURCES]).
Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
APIs), which is only available in a dedicated/onpremise Authlete server (contact [sales@authlete.com](mailto:sales@authlete.com)
for details).
**\[6] DYNAMIC SCOPES**
Get the value of `dynamicScopes` from the `/auth/authorization` API response. If the array contains
a scope which has not been granted to the client application by the end-user in the past, call
Authlete's `/auth/authorization/fail` API with `reason=CONSENT_REQUIRED` and use the response from
the API to generate a response to the client application. Otherwise, go to the next step (\[RESOURCES]).
Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
APIs) but dynamic scopes are not remembered as granted scopes.
**\[7] RESOURCES**
Get the value of `resources` from the `/auth/authorization` API response. The array represents
the values of the `resource` request parameters. If you want to reject the request, call Authlete's
`/auth/authorization/fail` API with `reason=INVALID_TARGET` and use the response from the API to
generate a response to the client application. Otherwise, go to the next step (\[ISSUE]).
See "Resource Indicators for OAuth 2.0" for details.
**\[8] ISSUE**
If all the above steps succeeded, the last step is to issue an authorization code, an ID token
and/or an access token. (There is a special case, though. In the case of `response_type=none`,
nothing is issued.) It can be performed by calling Authlete's `/auth/authorization/issue` API.
The API requires the following parameters. Prepare these parameters and call `/auth/authorization/issue`
API and use the response to generate a response to the client application.
* `ticket` (required)
This parameter represents a ticket which is exchanged with tokens at `/auth/authorization/issue`.
Use the value of `ticket` contained in the `/auth/authorization` API response.
* `subject` (required)
This parameter represents the unique identifier of the current end-user. It is often called "user ID"
and it may or may not be visible to the user. In any case, it is a number or a string assigned
to an end-user by the authorization server implementation. Authlete does not care about the format
of the value of subject, but it must consist of only ASCII letters and its length must not exceed 100.
When the value of `subject` parameter in the /auth/authorization API response is not `null`,
it is necessarily identical to the value of `subject` parameter in the `/auth/authorization/issue`
API request.
The value of this parameter will be embedded in an ID token as the value of `sub` claim. When
the value of `subject_type` configuration parameter of the client application is `PAIRWISE`,
the value of sub claim is different from the value specified by this parameter, See [8. Subject
Identifier Types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) of OpenID
Connect Core 1.0 for details about subject types.
You can use the `sub` request parameter to adjust the value of the `sub` claim in an ID token.
See the description of the `sub` request parameter for details.
* `authTime` (optional)
This parameter represents the time when the end-user authentication occurred. Its value is the
number of seconds from `1970-01-01`. The value of this parameter will be embedded in an ID token
as the value of `auth_time` claim.
* `acr` (optional)
This parameter represents the ACR (Authentication Context Class Reference) which the authentication
of the end-user satisfies. When `acrs` in the `/auth/authorization` API response is a non-empty
array and the value of `acrEssential` is `true`, the value of this parameter must be one of the
array elements. Otherwise, even `null` is allowed. The value of this parameter will be embedded
in an ID token as the value of `acr` claim.
* `claims` (optional)
This parameter represents claims of the end-user. "Claims" here are pieces of information about
the end-user such as `"name"`, `"email"` and `"birthdate"`. The authorization server implementation
is required to gather claims of the end-user, format the claim values into JSON and set the JSON
string as the value of this parameter.
The claims which the authorization server implementation is required to gather are listed in
`claims` parameter in the `/auth/authorization` API response.
For example, if claims parameter lists `"name"`, `"email"` and `"birthdate"`, the value of this
parameter should look like the following.
```json
{
"name": "John Smith",
"email": "john@example.com",
"birthdate": "1974-05-06"
}
```
`claimsLocales` parameter in the `/auth/authorization` API response lists the end-user's preferred
languages and scripts, ordered by preference. When `claimsLocales` parameter is a non-empty array,
its elements should be taken into account when the authorization server implementation gathers
claim values. Especially, note the excerpt below from [5.2. Claims Languages and Scripts](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsLanguagesAndScripts)
of OpenID Connect Core 1.0.
> When the OP determines, either through the `claims_locales` parameter, or by other means, that
> the End-User and Client are requesting Claims in only one set of languages and scripts, it is
> RECOMMENDED that OPs return Claims without language tags when they employ this language and script.
> It is also RECOMMENDED that Clients be written in a manner that they can handle and utilize Claims
> using language tags.
> If `claims` parameter in the `/auth/authorization` API response is `null` or an empty array,
> the value of this parameter should be `null`.
> See [5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)
> of OpenID Connect core 1.0 for claim names and their value formats. Note (1) that the authorization
> server implementation support its special claims ([5.1.2. Additional Claims](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims))
> and (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)).
> Read the specification of [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
> for details.
> The claim values in this parameter will be embedded in an ID token.
> Note that `idTokenClaims` parameter is available in the `/auth/authorization` API response.
> The parameter has the value of the `"id_token"` property in the `claims` request parameter or
> in the `"claims"` property in a request object. The value of this parameter should be considered
> when you prepare claim values.
* `properties` (optional)
Extra properties to associate with an access token and/or an authorization code that may be issued
by this request. Note that `properties` parameter is accepted only when `Content-Type` of the
request is `application/json`, so don't use `application/x-www-form-urlencoded` for details.
* `scopes` (optional)
Scopes to associate with an access token and/or an authorization code. If this parameter is `null`,
the scopes specified in the original authorization request from the client application are used.
In other cases, including the case of an empty array, the specified scopes will replace the original
scopes contained in the original authorization request.
Even scopes that are not included in the original authorization request can be specified. However,
as an exception, `openid` scope is ignored on the server side if it is not included in the original
request. It is because the existence of `openid` scope considerably changes the validation steps
and because adding `openid` triggers generation of an ID token (although the client application
has not requested it) and the behavior is a major violation against the specification.
If you add `offline_access` scope although it is not included in the original request, keep in
mind that the specification requires explicit consent from the user for the scope ([OpenID Connect
Core 1.0, 11. Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)).
When `offline_access` is included in the original request, the current implementation of Authlete's
`/auth/authorization` API checks whether the request has come along with `prompt` request parameter
and the value includes consent. However, note that the implementation of Authlete's `/auth/authorization/issue`
API does not perform such checking if `offline_access` scope is added via this `scopes` parameter.
* `sub` (optional)
The value of the `sub` claim in an ID token. If the value of this request parameter is not empty,
it is used as the value of the `sub` claim. Otherwise, the value of the `subject` request parameter
is used as the value of the `sub` claim. The main purpose of this parameter is to hide the actual
value of the subject from client applications.
Note that even if this `sub` parameter is not empty, the value of the subject request parameter
is used as the value of the subject which is associated with the access token.
## INTERACTION
When the value of `action` is `INTERACTION`, it means that the request from the client application
has no problem and requires the service to process the request with user interaction by an HTML form.
The purpose of the UI displayed to the end-user is to ask the end-user to grant authorization to
the client application. The items described below are some points which the service implementation
should take into account when it builds the UI.
**\[1] DISPLAY MODE**
The response from `/auth/authorization` API has `display` parameter. It is one of `PAGE` (default),
`POPUP`, `TOUCH` and `WAP` The meanings of the values are described in [3.1.2.1. Authentication
Request of OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).
Basically, the authorization server implementation should display the UI which is suitable for the
display mode, but it is okay for the authorization server implementation to "attempt to detect the
capabilities of the User Agent and present an appropriate display".
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.
**\[2] UI LOCALE**
The response from `/auth/authorization` API has `uiLocales` parameter. It it is not `null`, it lists
language tag values (such as `fr-CA`, `ja-JP` and `en`) ordered by preference. The service implementation
should display the UI in one of the language listed in the parameter when possible. It is ensured
that language tags listed in `uiLocales` are contained in the list of supported UI locales which
are specified by `supportedUiLocales` configuration parameter of the service.
**\[3] CLIENT INFORMATION**
The authorization server implementation should show information about the client application to
the end-user. The information is embedded in `client` parameter in the response from `/auth/authorization`
API.
**\[4] SCOPES**
A client application requires authorization for specific permissions. In OAuth 2.0 specification,
"scope" is a technical term which represents a permission. `scopes` parameter in the response
from `/auth/authorization` API is a list of scopes requested by the client application. The service
implementation should show the end-user the scopes.
The authorization server implementation may choose not to show scopes to which the end-user has
given consent in the past. To put it the other way around, the authorization server implementation
may show only the scopes to which the end-user has not given consent yet. However, if the value
of `prompts` response parameter contains `CONSENT`, the authorization server implementation has
to obtain explicit consent from the end-user even if the end-user has given consent to all the
requested scopes in the past.
Note that Authlete provides APIs to manage records of granted scopes (`/api/client/granted_scopes/*`
APIs), but the APIs work only in the case the Authlete server you use is a dedicated Authlete server
(contact [sales@authlete.com](mailto:sales@authlete.com) for details). In other words, the APIs of the shared Authlete server
are disabled intentionally (in order to prevent garbage data from being accumulated) and they
return 403 Forbidden.
It is ensured that the values in `scopes` parameter are contained in the list of supported scopes
which are specified by `supportedScopes` configuration parameter of the service.
**\[5] DYNAMIC SCOPES**
The authorization request may include dynamic scopes. The list of recognized dynamic scopes are
accessible by getDynamicScopes() method. See the description of the [DynamicScope](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/DynamicScope.html)
class for details about dynamic scopes.
**\[6] AUTHORIZATION DETAILS**
The authorization server implementation should show the end-user "authorization details" if the
request includes it. The value of `authorization_details` parameter in the response is the content
of the `authorization_details` request parameter.
See "OAuth 2.0 Rich Authorization Requests" for details.
**\[7] PURPOSE**
The authorization server implementation must show the value of the `purpose` request parameter if
it supports [OpenID Connect for Identity Assurance 1.0](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html).
See [8. Transaction-specific Purpose](https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#rfc.section.8)
in the specification for details.
Note that the value of `purpose` response parameter is the value of the purpose request parameter.
**\[7] END-USER AUTHENTICATION**
Necessarily, the end-user must be authenticated (= must login the service) before granting authorization
to the client application. Simply put, a login form is expected to be displayed for end-user authentication.
The service implementation must follow the steps described below to comply with OpenID Connect.
(Or just always show a login form if it's too much of a bother.)
* (i) Get the value of `prompts` response parameter. It corresponds to the value of the `prompt`
request parameter. Details of the request parameter are described in [3.1.2.1. Authentication
Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of OpenID Connect Core 1.0.
* (ii) If the value of `prompts` parameter is `SELECT_ACCOUNT` display a form to let the end-user
select on of his/her accounts for login. If `subject` response parameter is not `null`, it is the
end-user ID that the client application expects, so the value should be used to determine the value
of the login ID. Note that a subject and a login ID are not necessarily equal. If the value of
`subject` response parameter is `null`, the value of `loginHint` response parameter should be referred
to as a hint to determine the value of the login ID. The value of `loginHint` response parameter
is simply the value of the `login_hint` request parameter.
* (iii) If the value of `prompts` response parameter contains `LOGIN`, display a form to urge the
end-user to login even if the end-user has already logged in. If the value of `subject` response
parameter is not `null`, it is the end-user ID that the client application expects, so the value
should be used to determine the value of the login ID. Note that a subject and a login ID are not
necessarily equal. If the value of `subject` response parameter is `null`, the value of `loginHint`
response parameter should be referred to as a hint to determine the value of the login ID. The value
of `loginHint` response parameter is simply the value of the `login_hint` request parameter.
* (iv) If the value of `prompts` response parameter does not contain `LOGIN`, the authorization server
implementation does not have to authenticate the end-user if all the conditions described below
are satisfied. If any one of the conditions is not satisfied, show a login form to authenticate
the end-user.
* An end-user has already logged in the service.
* The login ID of the current end-user matches the value of `subject` response parameter.
This check is required only when the value of `subject` response parameter is a non-null value.
* The max age, which is the number of seconds contained in `maxAge` response parameter,
has not passed since the current end-user logged in your service. This check is required only when
the value of `maxAge` response parameter is a non-zero value.
* If the authorization server implementation does not manage authentication time of end-users
(= if the authorization server implementation cannot know when end-users logged in) and if the
value of `maxAge` response parameter is a non-zero value, a login form should be displayed.
* The ACR (Authentication Context Class Reference) of the authentication performed for
the current end-user satisfies one of the ACRs listed in `acrs` response parameter. This check is
required only when the value of `acrs` response parameter is a non-empty array.
In every case, the end-user authentication must satisfy one of the ACRs listed in `acrs` response
parameter when the value of `acrs` response parameter is a non-empty array and `acrEssential`
response parameter is `true`.
**\[9] GRANT/DENY BUTTONS**
The end-user is supposed to choose either (1) to grant authorization to the client application or
(2) to deny the authorization request. The UI must have UI components to accept the judgment by
the user. Usually, a button to grant authorization and a button to deny the request are provided.
When the value of `subject` response parameter is not `null`, the end-user authentication must be
performed for the subject, meaning that the authorization server implementation should repeatedly
show a login form until the subject is successfully authenticated.
The end-user will choose either (1) to grant authorization to the client application or (2) to
deny the authorization request. When the end-user chose to deny the authorization request, call
Authlete's `/auth/authorization/fail` API with `reason=DENIED` and use the response from the API
to generate a response to the client application.
When the end-user chose to grant authorization to the client application, the authorization server
implementation has to issue an authorization code, an ID token, and/or an access token to the client
application. (There is a special case. When `response_type=none`, nothing is issued.) Issuing the
tokens can be performed by calling Authlete's `/auth/authorization/issue` API. Read \[ISSUE] written
above in the description for the case of `action=NO_INTERACTION`.
## OpenAPI
````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/auth/authorization
openapi: 3.0.3
info:
title: Authlete API
description: ''
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: Service Management
description: >-
API endpoints for managing services, including creation, update, and
deletion of services.
x-tag-expanded: false
- name: Client Management
description: >-
API endpoints for managing OAuth clients, including creation, update, and
deletion of clients.
x-tag-expanded: false
- name: Authorization Endpoint
description: API endpoints for implementing OAuth 2.0 Authorization Endpoint.
x-tag-expanded: false
- name: Pushed Authorization Endpoint
description: >-
API endpoints for implementing OAuth 2.0 Pushed Authorization Requests
(PAR).
x-tag-expanded: false
- name: Token Endpoint
description: API endpoints for implementing OAuth 2.0 Token Endpoint.
x-tag-expanded: false
- name: Token Operations
description: >-
API endpoints for various token related operations, including creating,
revoking and deleting access_tokens with specified scopes.
x-tag-expanded: false
- name: Introspection Endpoint
description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
x-tag-expanded: false
- name: Revocation Endpoint
description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
x-tag-expanded: false
- name: UserInfo Endpoint
description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
x-tag-expanded: false
- name: JWK Set Endpoint
description: API endpoints for to generate JSON Web Key Set (JWKS) for a service.
x-tag-expanded: false
- name: Discovery Endpoint
description: API endpoints for implementing OpenID Connect Discovery.
x-tag-expanded: false
- name: Configuration Endpoint
description: API endpoint for accessing configuration settings for a service.
x-tag-expanded: false
- name: Dynamic Client Registration
description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration.
x-tag-expanded: false
- name: CIBA
description: >-
API endpoints for implementing Client-Initiated Backchannel Authentication
(CIBA).
x-tag-expanded: false
- name: Grant Management Endpoint
description: >-
API endpoint for implementing OAuth 2.0 grants, including grant management
actions like updating and revoking grants.
x-tag-expanded: false
- name: Jose Object
description: API endpoints for JOSE objects.
x-tag-expanded: false
- name: Device Flow
description: API endpoints for implementing OAuth 2.0 Device Flow
x-tag-expanded: false
- name: Federation Endpoint
description: API endpoints for implementing OpenID Federation using Authlete.
x-tag-expanded: false
- name: Verifiable Credential Issuer
description: >-
API endpoints for implementing and running a Verifiable Credential Issuer
(VCI).
x-tag-expanded: false
- name: Hardware Security Key
description: API endpoints for managing hardware security keys (HSK).
x-tag-expanded: false
- name: Utility Endpoints
description: API endpoints for various utility operations.
x-tag-expanded: false
- name: Native SSO
description: API endpoints for Native SSO
x-tag-expanded: false
paths:
/api/{serviceId}/auth/authorization:
post:
tags:
- Authorization Endpoint
summary: Process Authorization Request
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.
operationId: auth_authorization_api
parameters:
- in: path
name: serviceId
description: A service ID.
schema:
type: string
required: true
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'
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Authlete } from "@authlete/typescript-sdk";
const authlete = new Authlete({
bearer: process.env["AUTHLETE_BEARER"] ?? "",
});
async function run() {
const result = await authlete.authorization.processRequest({
serviceId: "",
authorizationRequest: {
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",
},
});
console.log(result);
}
run();
- lang: ruby
label: Ruby (SDK)
source: >-
require 'authlete_ruby_sdk'
Models = ::Authlete::Models
s = ::Authlete::Client.new(
bearer: ''
)
res = s.authorization.process_request(service_id: '',
authorization_request: Models::Components::AuthorizationRequest.new(
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'
))
unless res.authorization_response.nil?
# handle response
end
- lang: go
label: Go (SDK)
source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tauthlete \"github.com/authlete/authlete-go-sdk\"\n\t\"github.com/authlete/authlete-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := authlete.New(\n authlete.WithSecurity(os.Getenv(\"AUTHLETE_BEARER\")),\n )\n\n res, err := s.Authorization.ProcessRequest(ctx, \"\", components.AuthorizationRequest{\n 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\",\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.AuthorizationResponse != nil {\n // handle response\n }\n}"
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)
components:
schemas:
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.
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.
If the request does not contain `scope` parameter, this parameter is
a list of scopes which are registered as default.
If the authorization request does not have `scope` request parameter
and the service has not registered any default scope,
the value of this parameter is `null`.
It is ensured that scopes listed by this parameters are contained in
the list of supported scopes which are specified
by `supportedScopes` configuration parameter of the service.
Unsupported scopes in the authorization request do not cause
an error and are just ignored.
OpenID Connect defines some scope names which need to be treated
specially. The table below lists the special scope names.
| Name | Description |
| --- | --- |
| `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". |
| `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).
|
| `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).
|
| `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).
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). |
| `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).
|
| `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).
> 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).
|
Note that, if `response_type` request parameter does not contain
code, `offline_acccess` scope is removed from this list even
when scope request parameter contains `offline_access`. This
behavior is a requirement written in
[OpenID Connect Core 1.0, 11. Offline
Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess).
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: >
A client application may request certain claims be embedded in an
ID token or in a response from the userInfo endpoint.
There are several ways. Including the `claims` request parameter
and including the `claims` property in a request object are such
examples.
In both the cases, the value of the `claims` parameter/property is
JSON. Its format is described in [5.5. Requesting Claims using the
"claims"
Request
Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
The following is an excerpt from the specification.
You can find `userinfo` and `id_token` are top-level properties.
```json
{
"userinfo":
{
"given_name": { "essential": true },
"nickname": null,
"email": { "essential": true },
"email_verified": { "essential": true },
"picture": null,
"http://example.info/claims/groups": null
},
"id_token":
{
"auth_time": { "essential": true },
"acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
}
}
```
This value of this property is the value of the `id_token`
property in JSON format.
For example, if the JSON above is included in an authorization
request, this property holds JSON equivalent to the following.
```json
{
"auth_time": { "essential": true },
"acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
}
```
Note that if a request object is given and it contains the
`claims` property and if the `claims` request parameter is also
given,
this property holds the former value.
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: >
A client application may request certain claims be embedded in an
ID token or in a response from the userInfo endpoint.
There are several ways. Including the `claims` request parameter
and including the `claims` property in a request object are such
examples.
In both the cases, the value of the `claims` parameter/property is
JSON. Its format is described in [5.5. Requesting Claims using the
"claims"
Request
Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter).
The following is an excerpt from the specification. You can find
`userinfo` and `id_token` are top-level properties.
```json
{
"userinfo":
{
"given_name": { "essential": true },
"nickname": null,
"email": { "essential": true },
"email_verified": { "essential": true },
"picture": null,
"http://example.info/claims/groups": null
},
"id_token":
{
"auth_time": { "essential": true },
"acr": { "values": [ "urn:mace:incommon:iap:silver" ] }
}
}
````
The value of this property is the value of the `userinfo` property
in JSON format.
For example, if the JSON above is included in an authorization
request, this property holds JSON equivalent to the following.
```json
{
"given_name": { "essential": true },
"nickname": null,
"email": { "essential": true },
"email_verified": { "essential": true },
"picture": null,
"http://example.info/claims/groups": null
}
```
Note that if a request object is given and it contains the
`claims` property and if the `claims` request parameter is also
given,
the value of this property holds the former value.
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.
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`).
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: >
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 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 service 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.
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: >
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 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 of the service is `true`.
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
operations.
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.
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
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
is used for service authentication in API calls.
tokenBatchNotificationEndpoint:
type: string
format: uri
description: >
The endpoint for batch token notifications. This endpoint is called
when
multiple tokens are issued or revoked in a batch operation.
clientAssertionAudRestrictedToIssuer:
type: boolean
description: >
The flag indicating whether the audience of client assertion JWTs
must
match the issuer identifier of this service.
serviceOwnerNumber:
type: integer
format: int32
readOnly: true
description: >
The number of the organization that owns this service. This value
is
assigned by Authlete.
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
developers log into the developer portal.
developerAuthenticationCallbackApiKey:
type: string
description: >
The API key for basic authentication at the developer
authentication
callback endpoint.
developerAuthenticationCallbackApiSecret:
type: string
description: >
The API secret for basic authentication at the developer
authentication
callback endpoint.
supportedSnses:
type: array
items:
type: string
enum:
- FACEBOOK
description: |
Social login services (SNS) that this service supports for end-user
authentication.
snsCredentials:
type: array
items:
$ref: '#/components/schemas/sns_credentials'
description: |
The credentials for social login services (SNS) that are used for
end-user authentication.
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.
The predefined service metadata is listed in the following table.
| Key | Description |
| --- | --- |
| `clientCount` | The number of client applications which belong to this service. |
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: >
Differences between rules in OpenID Connect Core 1.0 and ones in
JAR are as follows.
- JAR requires that a request object be always -signed.
- JAR does not allow request parameters outside a request object to be referred to.
- OIDC Core 1.0 requires that response_type request parameter exist outside a request object even if the request object includes the request parameter.
- OIDC Core 1.0 requires that scope request parameter exist outside a request object if the authorization request is an
- OIDC request even if the request object includes the request parameter.
If this flag is set to `false` and the value of
`requestObjectRequired` is `true`, 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.
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: >
This 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/).
The aliases will be embedded in the response from the discovery
endpoint like the following.
```json
{
......,
"mtls_endpoint_aliases": {
"token_endpoint": "https://mtls.example.com/token",
"revocation_endpoint": "https://mtls.example.com/revo",
"introspection_endpoint": "https://mtls.example.com/introspect"
}
}
```
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.
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'
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
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.
dynamic_scope:
type: object
properties:
name:
type: string
description: The scope name.
value:
type: string
description: The scope value.
grant_management_action:
type: string
description: >
The grant management action of the device authorization request.
The `grant_management_action` request parameter is defined in
[Grant Management for OAuth
2.0](https://openid.net/specs/fapi-grant-management.html).
enum:
- CREATE
- QUERY
- REPLACE
- REVOKE
- MERGE
grant:
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'
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: |
```
{
"credential_issuer": "...",
"credential_configuration_ids": [ ... ],
"grants": { ... }
}
```
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.
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.
tagged_value:
type: object
properties:
tag:
type: string
description: The language tag part.
value:
type: string
description: The value part.
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
sns_credentials:
type: object
properties:
sns:
type: string
description: SNS.
apiKey:
type: string
description: API key.
apiSecret:
type: string
description: API secret.
pair:
type: object
properties:
key:
type: string
description: The key part.
value:
type: string
description: The value part.
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
response_type:
type: string
enum:
- NONE
- CODE
- TOKEN
- ID_TOKEN
- CODE_TOKEN
- CODE_ID_TOKEN
- ID_TOKEN_TOKEN
- CODE_ID_TOKEN_TOKEN
service_profile:
type: string
enum:
- FAPI
- OPEN_BANKING
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
named_uri:
type: object
properties:
name:
type: string
uri:
type: string
format: uri
jws_alg:
type: string
nullable: true
description: >
The signature algorithm for JWT. This value is represented on 'alg'
attribute
of the header of JWT.
it's semantics depends upon where is this defined, for instance:
- 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).
- 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).
- 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).
enum:
- NONE
- HS256
- HS384
- HS512
- RS256
- RS384
- RS512
- ES256
- ES384
- ES512
- PS256
- PS384
- PS512
- ES256K
- EdDSA
claim_type:
type: string
enum:
- NORMAL
- AGGREGATED
- DISTRIBUTED
delivery_mode:
type: string
enum:
- PING
- POLL
- PUSH
user_code_charset:
type: string
description: >
The character set for end-user verification codes (`user_code`) for
Device Flow.
enum:
- BASE20
- NUMERIC
verified_claims_validation_schema:
type: string
description: |
The verified claims validation schema set.
enum:
- standard
- standard+id_document
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"`.
attachment_type:
type: string
description: >
Supported attachment types. This property corresponds to the
`attachments_supported`
server metadata which was added by the third implementer's draft of OpenID Connect
for Identity Assurance 1.0.
enum:
- EMBEDDED
- EXTERNAL
client_registration_type:
type: string
description: |
Values for the `client_registration_types` RP metadata and the
`client_registration_types_supported` OP metadata that are defined in
[OpenID Connect Federation 1.0](https://openid.net/specs/openid-connect-federation-1_0.html).
enum:
- AUTOMATIC
- EXPLICIT
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
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
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_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.
grant_scope:
type: object
properties:
scope:
type: string
description: |
Space-delimited scopes.
resource:
type: array
items:
type: string
description: |
List of resource indicators.
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.
responses:
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001201
resultMessage: '[A001201] /auth/authorization, TLS must be used.'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001202
resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001215
resultMessage: >-
[A001215] /auth/authorization, The client (ID = 26837717140341) is
locked.
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/result'
example:
resultCode: A001101
resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Authenticate every request with a **Service Access Token** or
**Organization Token**.
Set the token value in the `Authorization: Bearer ` header.
**Service Access Token**: Scoped to a single service. Use when
automating service-level configuration or runtime flows.
**Organization Token**: Scoped to the organization; inherits permissions
across services. Use for org-wide automation or when managing multiple
services programmatically.
Both token types are issued by the Authlete console or provisioning
APIs.
````