openapi: 3.0.3 info: title: Authlete Authorization Endpoint Introspection Endpoint API description: "Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the \nplatform is configurable via API. This documentation will help you authenticate and integrate with Authlete to \nbuild powerful OAuth 2.0 and OpenID Connect servers.\n\nAt a high level, the Authlete API is grouped into two categories:\n\n- **Management APIs**: Enable you to manage services and clients.\n- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.\n\n## \U0001F310 API Servers\n\nAuthlete is a global service with clusters available in multiple regions across the world:\n\n- \U0001F1FA\U0001F1F8 **US**: `https://us.authlete.com`\n- \U0001F1EF\U0001F1F5 **Japan**: `https://jp.authlete.com`\n- \U0001F1EA\U0001F1FA **Europe**: `https://eu.authlete.com`\n- \U0001F1E7\U0001F1F7 **Brazil**: `https://br.authlete.com`\n\nOur customers can host their data in the region that best meets their requirements.\n\n## \U0001F511 Authentication\n\nAll API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n### Getting Your Access Token\n\nAuthlete supports two types of access tokens:\n\n**Service Access Token** - Scoped to a single service (authorization server instance)\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to your service → **Settings** → **Access Tokens**\n3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)\n4. Copy the generated token\n\n**Organization Token** - Scoped to your entire organization\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to **Organization Settings** → **Access Tokens**\n3. Click **Create Token** and select org-level permissions\n4. Copy the generated token\n\n> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only \n> access their specific service, while organization tokens can access all services within your org.\n\n### Token Security Best Practices\n\n- **Never commit tokens to version control** - Store in environment variables or secure secret managers\n- **Rotate regularly** - Generate new tokens periodically and revoke old ones\n- **Scope appropriately** - Request only the permissions your application needs\n- **Revoke unused tokens** - Delete tokens you're no longer using from the console\n\n### Quick Test\n\nVerify your token works with a simple API call:\n\n```bash\ncurl -X GET https://us.authlete.com/api/service/get/list \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## \U0001F393 Tutorials\n\nIf you're new to Authlete or want to see sample implementations, these resources will help you get started:\n\n- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)\n- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)\n\n## \U0001F6E0 Contact Us\n\nIf you have any questions or need assistance, our team is here to help:\n\n- [Contact Page](https://www.authlete.com/contact/)\n" version: 3.0.16 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - description: 🇺🇸 US Cluster url: https://us.authlete.com - description: 🇯🇵 Japan Cluster url: https://jp.authlete.com - description: 🇪🇺 Europe Cluster url: https://eu.authlete.com - description: 🇧🇷 Brazil Cluster url: https://br.authlete.com security: - bearer: [] tags: - name: Introspection Endpoint description: API endpoints for implementing OAuth 2.0 Introspection Endpoint. x-tag-expanded: false paths: /api/{serviceId}/auth/introspection: post: summary: Process Introspection Request description: 'This API gathers information about an access token. ' x-mint: metadata: description: This API gathers information about an access token. content: ' This API is supposed to be called from within the implementations of protected resource endpoints of the authorization server implementation in order to get information about the access token which was presented by the client application. In general, a client application accesses a protected resource endpoint of a service with an access token, and the implementation of the endpoint checks whether the presented access token has enough privileges (= scopes) to access the protected resource before returning the protected resource to the client application. To achieve this flow, the endpoint implementation has to know detailed information about the access token. Authlete `/auth/introspection` API can be used to get such information. The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type 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 string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration parameter of the service is Bearer), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application does not contain an access token (= the request from the authorization server implementation to Authlete does not contain `token` request parameter). A response with HTTP status of "400 Bad Request" must be returned to the client application and the content type must be `application/json`. The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## UNAUTHORIZED When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has expired. The value of `responseContent` is a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORBIDDEN When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required scopes or that the subject associated with the access token is different from the subject contained in the request. A response with HTTP status of "400 Bad Request" must be returned to the client application and the content type must be `application/json`. The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation wants to return an error response to the client application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration parameter of the service is Bearer), the value of `responseContent` can be used as the value of `WWW-Authenticate` header. The following is an example response which complies with RFC 6750. ``` HTTP/1.1 403 Forbidden WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## OK When the value of `action` is `OK`, it means that the access token which the client application presented is valid (= exists and has not expired). The implementation of the protected resource endpoint is supposed to return the protected resource to the client application. When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid_request\""`. This is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate "400 Bad Request". The implementation of the protected resource endpoint may use this string to tell the client application that the request was bad (e.g. in case necessary request parameters for the protected resource endpoint are missing). However, in such a case, the implementation should generate a more informative error message to help developers of client applications. The following is an example error response which complies with RFC 6750. ``` HTTP/1.1 400 Bad Request WWW-Authenticate: {responseContent} Cache-Control: no-store Pragma: no-cache ``` Basically, The value of `responseContent` is a string which describes the error in the format of [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However, if the service has selected another different token type, the service has to generate error messages for itself. _**JWT-based access token**_ Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service (see the description of the Service class for details). `/api/auth/introspection` API can accept access tokens in JWT format. However, note that the API does not return information contained in a given JWT-based access token but returns information stored in the database record which corresponds to the given JWT-based access token. Because attributes of the database record can be modified after the access token is issued (for example, by using `/api/auth/token/update` API), information returned by `/api/auth/introspection` API and information the given JWT-based access token holds may be different. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/introspection_request' example: token: VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI subject: john scopes: - history.read - timeline.read application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/introspection_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/introspection_response' example: resultCode: A056001 resultMessage: '[A056001] The access token is valid.' action: OK clientAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value clientId: 26478243745571 clientIdAlias: my-client clientIdAliasUsed: false existent: true expiresAt: 1640416873000 refreshable: true responseContent: Bearer error="invalid_request" scopes: - history.read - timeline.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value subject: john sufficient: true usable: true '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_introspection_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/introspection \ -H ''Content-Type:application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "token": "VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI", "scopes": [ "history.read", "timeline.read" ] }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); IntrospectionRequest req = new IntrospectionRequest(); req.setToken("VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI"); req.setScopes(new String[] { "history.read", "timeline.read" }); api.introspection(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = IntrospectionRequest() req.token = ''VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI'' req.scopes = [ ''history.read'', ''timeline.read'' ] api.introspection(req) ' tags: - Introspection Endpoint /api/{serviceId}/auth/introspection/standard: post: summary: Process OAuth 2.0 Introspection Request description: 'This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection). ' x-mint: metadata: description: This API exists to help your authorization server provide its own introspection API which complies with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection). content: ' This API is supposed to be called from within the implementations of the introspection endpoint of your service. The authorization server implementation should retrieve the value of `action` from the response and take the following steps according to the value. In general, a client application accesses a protected resource endpoint of a service with an access token, and the implementation of the endpoint checks whether the presented access token has enough privileges (= scopes) to access the protected resource before returning the protected resource to the client application. To achieve this flow, the endpoint implementation has to know detailed information about the access token. Authlete `/auth/introspection` API can be used to get such information. The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response body of error responses. --- The following illustrates an example response which the introspection endpoint of the authorization server implementation generates and returns to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. This happens when the request from the client did not include the token request parameter. See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in RFC 7662 for details about requirements for introspection requests. The HTTP status of the response returned to the client application should be "400 Bad Request". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response body of error responses. The following illustrates an example response which the introspection endpoint of the authorization server implementation generates and returns to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json {responseContent} ``` ## OK When the value of `action` is `OK`, the request from the client application is valid. The HTTP status of the response returned to the client application must be "200 OK" and its content type must be `application/json`. The value of `responseContent` is a JSON string which complies with the introspection response defined in "2.2. Introspection Response" in RFC7662. --- The following illustrates the response which the introspection endpoint of your authorization server implementation should generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: application/json {responseContent} ``` Note that RFC 7662 says _"To prevent token scanning attacks, **the endpoint MUST also require some form of authorization to access this endpoint**"_. This means that you have to protect your introspection endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected. In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection request does not satisfy authorization requirements imposed by your introspection endpoint. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/standard_introspection_request' example: parameters: token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/standard_introspection_request' responses: '200': description: Token introspection completed successfully content: application/json: schema: $ref: '#/components/schemas/standard_introspection_response' example: resultCode: A145001 resultMessage: '[A145001] Introspection was performed successfully (type=access_token, active=true).' action: OK responseContent: '{\"sub\":\"john\",\"scope\":\"history.read timeline.read\",\"iss\":\"https://my-service.example.com\",\"active\":true,\"token_type\":\"Bearer\",\"exp\":1640416873,\"client_id\":\"26478243745571\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_introspection_standard_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/introspection/standard \ -H "Content-Type:application/json" \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "parameters":"token=VFGsNK-5sXiqterdaR7b5QbRX9VTwVCQB87jbr2_xAI&token_type_hint=access_token" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); StandardIntrospectionRequest req = new StandardIntrospectionRequest(); req.setParameters(...); api.standardIntrospection(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = StandardIntrospectionRequest() req.parameters = ... api.standardIntrospection(req) ' tags: - Introspection Endpoint components: schemas: tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. 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' grant_scope: type: object properties: scope: type: string description: 'Space-delimited scopes. ' resource: type: array items: type: string description: 'List of resource indicators. ' 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 introspection_request: type: object required: - token properties: token: type: string description: An access token to introspect. scopes: type: array items: type: string description: 'A string array listing names of scopes which the caller (= a protected resource endpoint of the service) requires. When the content type of the request from the service is `application/x-www-form-urlencoded`, the format of `scopes` is a space-separated list of scope names. If this parameter is a non-empty array and if it contains a scope which is not covered by the access token,`action=FORBIDDEN` with `error=insufficient_scope` is returned from Authlete. ' subject: type: string description: 'A subject (= a user account managed by the service) whom the caller (= a protected resource endpoint of the service) requires. If this parameter is not `null` and if the value does not match the subject who is associated with the access token, `action=FORBIDDEN` with `error=invalid_request` is returned from Authlete. ' clientCertificate: type: string description: 'Client certificate in PEM format, used to validate binding against access tokens using the TLS client certificate confirmation method. ' dpop: type: string description: '`DPoP` header presented by the client during the request to the resource server. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. ' htm: type: string description: 'HTTP method of the request from the client to the protected resource endpoint. This field is used to validate the `DPoP` header. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. ' htu: type: string description: 'URL of the protected resource endpoint. This field is used to validate the `DPoP` header. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. ' resources: type: array items: type: string description: 'The resources specified by the `resource` request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details. ' acrValues: type: array items: type: string description: 'Authentication Context Class Reference values one of which the user authentication performed during the course of issuing the access token must satisfy. ' maxAge: type: integer format: int64 description: 'The maximum authentication age which is the maximum allowable elapsed time since the user authentication was performed during the course of issuing the access token. ' requiredComponents: type: array items: type: string description: 'HTTP Message Components required to be in the signature. If absent, defaults to [ "@method", "@target-uri", "authorization" ]. ' uri: type: string description: 'The full URL of the userinfo endpoint. ' message: type: string description: 'The HTTP message body of the request, if present. ' headers: type: array items: $ref: '#/components/schemas/pair' description: 'HTTP headers to be included in processing the signature. If this is a signed request, this must include the Signature and Signature-Input headers, as well as any additional headers covered by the signature. ' targetUri: type: string description: 'The target URI of the resource request, including the query part, if any. ' x-mint: metadata: description: The target URI of the resource request, including the query part, if any. content: ' This parameter is used as the value of the @target-uri derived component for HTTP message signatures [RFC 9421 HTTP Message Signatures, Section 2.2.2. Target URI](https://www.rfc-editor.org/rfc/rfc9421.html#section-2.2.2)). Additionally, other derived components such as `@authority`, `@scheme`, `@path`, `@query` and `@query-param` are computed from this parameter. When this parameter is omitted, the value of the `htu` parameter is used. The `htu` parameter represents the URL of the resource endpoint, which is identical to the target URI of the resource request as long as the request does not include a query component. Conversely, if the resource request includes a query component, the value of the `htu` parameter will not match the target URI, and in that case, the HTTP message signature verification will fail. If neither this `targetUri` parameter nor the `htu` parameter is specified, the target URI is considered unavailable. If HTTP message signing requires the target-uri derived component or other derived components computed based on the target URI, the HTTP message signature verification will fail. ' dpopNonceRequired: type: boolean description: 'The flag indicating whether to check if the DPoP proof JWT includes the expected `nonce` value. If this request parameter is set to `true` or if the service''s `dpopNonceRequired` property is set to `true`, the `/auth/introspection` API checks if the DPoP proof JWT includes the expected `nonce` value. In this case, the response from the `/auth/introspection` API will include the `dpopNonce` response parameter, which should be used as the value of the DPoP-Nonce HTTP header. ' requestBodyContained: type: boolean description: 'The flag indicating whether the resource request contains a request body. When the resource request must comply with the HTTP message signing requirements defined in the FAPI 2.0 Message Signing specification, the `"content-digest"` component identifier must be included in the signature base of the HTTP message signature (see [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) if the resource request contains a request body. When this `requestBodyContained` parameter is set to `true`, Authlete checks whether `"content-digest"` is included in the signature base, if the FAPI profile applies to the resource request. ' standard_introspection_request: type: object required: - parameters properties: parameters: type: string description: 'Request parameters which comply with the introspection request defined in "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in RFC 7662. The implementation of the introspection endpoint of your authorization server will receive an HTTP POST [[RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231)] request with parameters in the `application/x-www-form-urlencoded` format. It is the entity body of the request that Authlete''s `/api/auth/introspection/standard` API expects as the value of `parameters`. ' withHiddenProperties: type: boolean description: 'Flag indicating whether to include hidden properties in the output. Authlete has a mechanism whereby to associate arbitrary key-value pairs with an access token. Each key-value pair has a hidden attribute. By default, key-value pairs whose hidden attribute is set to `true` are not embedded in the standard introspection output. If the `withHiddenProperties` request parameter is given and its value is `true`, `/api/auth/introspection/standard API includes all the associated key-value pairs into the output regardless of the value of the hidden attribute. ' rsUri: type: string description: 'The URI of the resource server making the introspection request. If the `rsUri` request parameter is given and the token has audience values, Authlete checks if the value of the `rsUri` request parameter is contained in the audience values. If not contained, Authlete generates an introspection response with the `active` property set to `false`. The `rsUri` request parameter is required when the resource server requests a JWT introspection response, i.e., when the value of the `httpAcceptHeader` request parameter is set to `"application/token-introspection+jwt"`. ' httpAcceptHeader: type: string description: 'The value of the `HTTP Accept` header in the introspection request. If the value of the `httpAcceptHeader` request parameter is `"application/token-introspection+jwt"`, Authlete generates a JWT introspection response. See "[4. Requesting a JWT Response](https://www.rfc-editor.org/rfc/rfc9701.html#section-4)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)" for more details. ' introspectionSignAlg: type: string description: 'The JWS `alg` algorithm for signing the introspection response. This parameter corresponds to `introspection_signed_response_alg` defined in "[6. Client Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)". The default value is `RS256`. ' introspectionEncryptionAlg: type: string description: 'The JWE `alg` algorithm for encrypting the introspection response. This parameter corresponds to `introspection_encrypted_response_alg` defined in "[6. Client Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)". If the `introspectionEncryptionAlg` request parameter is specified, Authlete generates a JWT introspection response encrypted with the algorithm by this property and the algorithm specified by the `introspectionEncryptionEnc` request parameter. ' introspectionEncryptionEnc: type: string description: 'The JWE `enc` algorithm for encrypting the introspection response. This parameter corresponds to `introspection_encrypted_response_enc` defined in "[6. Client Metadata](https://www.rfc-editor.org/rfc/rfc9701.html#section-6)" of "[RFC 9701: JWT Response for OAuth Token Introspection](https://www.rfc-editor.org/rfc/rfc9701.html)". The default value is `A128CBC_HS256`. ' sharedKeyForSign: type: string description: 'The shared key for signing the introspection response with a symmetric algorithm. The `sharedKeyForSign` request parameter is required when the introspection response is requested to be signed with a symmetric algorithm. ' sharedKeyForEncryption: type: string description: 'The shared key for encrypting the introspection response with a symmetric algorithm. The `sharedKeyForEncryption` request parameter is required when the introspection response is requested to be encrypted with a symmetric algorithm. ' publicKeyForEncryption: type: string description: 'The public key for signing the introspection response with an asymmetric algorithm. The `publicKeyForEncryption` request parameter is required when the introspection response is requested to be encrypted with an asymmetric algorithm. ' pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. 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. ' 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' 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. ' introspection_response: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. action: type: string enum: - INTERNAL_SERVER_ERROR - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: 'The content that the authorization server implementation can use as the value of `WWW-Authenticate` header on errors. ' clientId: type: integer format: int64 description: The client ID. clientIdAlias: type: string description: 'The client ID alias when the token request was made. If the client did not have an alias, this parameter is `null`. Also, if the token request was invalid and it failed to identify a client, this parameter is `null`. ' clientIdAliasUsed: type: boolean description: 'The flag which indicates whether the client ID alias was used when the token request was made. `true` if the client ID alias was used when the token request was made. ' expiresAt: type: integer format: int64 description: 'The time at which the access token expires. The value is represented in milliseconds since the Unix epoch (1970-01-01). ' subject: type: string description: 'The subject who is associated with the access token. The value of this property is `null` if the access token was issued using the flow of [Client Credentials Grant](tools.ietf.org/html/rfc6749#section-4.4). ' scopes: type: array items: type: string description: 'The scopes covered by the access token. ' existent: type: boolean description: '`true` if the access token exists. ' usable: type: boolean description: 'true` if the access token is usable (= exists and has not expired). ' sufficient: type: boolean description: '`true` if the access token exists. ' refreshable: type: boolean description: '`true` if the access token can be refreshed using the associated refresh token which had been issued along with the access token. `false` if the refresh token for the access token has expired or the access token has no associated refresh token. ' properties: type: array items: $ref: '#/components/schemas/property' description: The extra properties associated with the access token. certificateThumbprint: type: string description: 'The client certificate thumbprint used to validate the access token. ' resources: type: array items: type: string description: 'The target resources. This represents the resources specified by the `resource` request parameters or by the `resource` property in the request object. See "Resource Indicators for OAuth 2.0" for details. ' accessTokenResources: type: array items: type: string description: 'The target resources this proeprty holds may be the same as or different from the ones `resource` property holds. ' x-mint: metadata: description: The target resources this proeprty holds may be the same as or different from the ones `resource` property holds. content: ' In some flows, the initial request and the subsequent token request are sent to different endpoints. Example flows are the Authorization Code Flow, the Refresh Token Flow, the CIBA Ping Mode, the CIBA Poll Mode and the Device Flow. In these flows, not only the initial request but also the subsequent token request can include the `resource` request parameters. The purpose of the `resource` request parameters in the token request is to narrow the range of the target resources from the original set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources holded by the `resource` proeprty and the ones holded by this property are different. This property holds the narrowed set of target resources. See "Resource Indicators for OAuth 2.0" for details. ' authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of this service that the client application belongs to. ' clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of the client. ' scopeDetails: type: array items: $ref: '#/components/schemas/scope' description: 'The scopes property of this class is a list of scope names. The property does not hold information about scope attributes. This scopeDetails property was newly created to convey information about scope attributes. ' 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' forExternalAttachment: type: boolean description: 'the flag which indicates whether the access token is for an external attachment. ' consentedClaims: type: array items: type: string description: 'the claims that the user has consented for the client application to know. ' grantType: $ref: '#/components/schemas/grant_type' acr: type: string description: 'The Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token. ' authTime: type: integer format: int64 description: 'The time when the user authentication was performed during the course of issuing the access token. ' clientEntityId: type: string description: 'The entity ID of the client. ' clientEntityIdUsed: type: boolean description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made. ' forCredentialIssuance: type: boolean description: The flag indicating whether the token is for credential issuance. cnonce: type: string description: The c_nonce cnonceExpiresAt: type: integer format: int64 description: The time at which the `c_nonce` expires. issuableCredentials: type: string description: The credentials that can be obtained by presenting the access token. dpopNonce: type: string description: 'The expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. ' responseSigningRequired: type: boolean description: 'The flag indicating whether the HTTP response from the protected resource endpoint must include an HTTP message signature ([RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)) in compliance with [FAPI 2.0 Message Signing](https://openid.bitbucket.io/fapi/fapi-2_0-message-signing.html). When this response parameter is `true`, the HTTP response from the protected resource endpoint must include the `Signature` and `Signature-Input` HTTP fields. ' metadataDocumentLocation: type: string format: uri description: 'The location of the client''s metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. ' metadataDocumentUsed: type: boolean description: 'Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ' standard_introspection_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 - OK - JWT description: The next action that the authorization server implementation should take. responseContent: type: string description: 'The content that the authorization server implementation is to return to the client application. ' authorization_details_element: type: object required: - type properties: type: type: string description: 'The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. ' locations: type: array items: type: string description: 'The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. ' actions: type: array items: type: string description: 'The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. ' dataTypes: type: array items: type: string description: 'From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. ' identifier: type: string description: 'The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. ' privileges: type: array items: type: string description: 'The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. ' otherFields: type: string description: 'The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. ' result: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. responses: '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' 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. '