openapi: 3.0.3 info: title: Authlete Authorization Endpoint Token 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: Token Endpoint description: API endpoints for implementing OAuth 2.0 Token Endpoint. x-tag-expanded: false paths: /api/{serviceId}/auth/token: post: summary: Process Token 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. ' x-mint: metadata: description: This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. content: ' This API is supposed to be called from with the implementation of the token endpoint of the service. The endpoint implementation must extract the request parameters from the token request from the client application and pass them as the value of parameters request parameter to Authlete''s `/auth/token` API. The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the token request. In addition, if the token endpoint of the authorization server implementation supports basic authentication as a means of [client authentication](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3), the client credentials must be extracted from `Authorization` header and they must be passed as `clientId` request parameter and `clientSecret` request parameter to Authlete''s `/auth/token` API. The following code snippet is an example in JAX-RS showing how to extract request parameters from the token request and client credentials from Authorization header. ```java @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public Response post( @HeaderParam(HttpHeaders.AUTHORIZATION) String auth, String parameters) { // Convert the value of Authorization header (credentials of // the client application), if any, into BasicCredentials. BasicCredentials credentials = BasicCredentials.parse(auth); // The credentials of the client application extracted from // ''Authorization'' header. These may be null. String clientId = credentials == null ? null : credentials.getUserId(); String clientSecret = credentials == null ? null : credentials.getPassword(); // Process the given parameters. return process(parameters, clientId, clientSecret); } ``` The response from `/auth/token` API has some parameters. Among them, it is action parameter that the service 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 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. ## INVALID_CLIENT When the value of `action` is `INVALID_CLIENT`, it means that authentication of the client failed. In this case, the HTTP status of the response to the client application is either "400 Bad Request" or "401 Unauthorized". This requirement comes from [RFC 6749, 5.2. Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). The description about `invalid_client` shown below is an excerpt from RFC 6749. --- Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the `Authorization` request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the `WWW-Authenticate` response header field matching the authentication scheme used by the client. --- In either case, the value of `responseContent` is a JSON string which can be used as the entity body of the response to the client application. --- The following illustrate responses which the service implementation must 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} ``` ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## BAD_REQUEST When the value of `action` is `BAD_REQUEST`, it means that the request from the client application is invalid. 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 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} ``` ## PASSWORD When the value of `"action"` is `"PASSWORD"`, it means that the request from the client application is valid and `grant_type` is `"password"`. That is, the flow is ["Resource Owner Password Credentials"](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.3). In this case, {@link #getUsername()} returns the value of `"username"` request parameter and {@link #getPassword()} returns the value of {@code "password"} request parameter which were contained in the token request from the client application. The service implementation must validate the credentials of the resource owner (= end-user) and take either of the actions below according to the validation result. 1. When the credentials are valid, call Authlete''s /auth/token/issue} API to generate an access token for the client application. The API requires `"ticket"` request parameter and `"subject"` request parameter. Use the value returned from {@link #getTicket()} method as the value for `"ticket"` parameter. 2. The response from `/auth/token/issue` API ({@link TokenIssueResponse}) contains data (an access token and others) which should be returned to the client application. Use the data to generate a response to the client application. 3. When the credentials are invalid, call Authlete''s {@code /auth/token/fail} API with `reason=`{@link TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response for the client application. The API requires `"ticket"` request parameter. Use the value returned from {@link #getTicket()} method as the value for `"ticket"` parameter. 4. The response from `/auth/token/fail` API ({@link TokenFailResponse}) contains error information which should be returned to the client application. Use it to generate a response to the client application. ## OK When the value of `action` is `OK`, it means that the request from the client application is valid and an access token, and optionally an ID token, is ready to be issued. The HTTP status of the response returned to the client application must be "200 OK" and the content type must be `application/json`. The value of `responseContent` is a JSON string which contains an access token (and optionally an ID token), so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## TOKEN_EXCHANGE (Authlete 2.3 onwards) When the value of `"action"` is `"TOKEN_EXCHANGE"`, it means that the request from the client application is a valid token exchange request (cf. [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)) and that the request has already passed the following validation steps. 1. Confirm that the value of the `requested_token_type` request parameter is one of the registered token type identifiers if the request parameter is given and its value is not empty. 2. Confirm that the `subject_token` request parameter is given and its value is not empty. 3. Confirm that the `subject_token_type` request parameter is given and its value is one of the registered token type identifiers. 4. Confirm that the `actor_token_type` request parameter is given and its value is one of the registered token type identifiers if the `actor_token` request parameter is given and its value is not empty. 5. Confirm that the `actor_token_type` request parameter is not given or its value is empty when the `actor_token` request parameter is not given or its value is empty. Furthermore, Authlete performs additional validation on the tokens specified by the `subject_token` request parameter and the `actor_token` request parameter according to their respective token types as shown below. ## Token Validation Steps \*Token Type: `urn:ietf:params:oauth:token-type:jwt`\* 1. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html]. 2. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() tokenExchangeEncryptedJwtRejected} flag of the service is `true` or (b) skip remaining validation steps when the flag is `false`. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself when one is used as an input token with the token type { @code "urn:ietf:params:oauth:token-type:jwt" }. 3. Confirm that the current time has not reached the time indicated by the `exp` claim if the JWT contains the claim. 4. Confirm that the current time is equal to or after the time indicated by the `iat` claim if the JWT contains the claim. 5.Confirm that the current time is equal to or after the time indicated by the `nbf` claim if the JWT contains the claim. 6. Check if the JWT is signed and if it is not signed, then (a) reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() tokenExchangeUnsignedJwtRejected} flag of the service is `true` or (b) finish validation on the input token. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself when a signed JWT is used as an input token with the token type `"urn:ietf:params:oauth:token-type:jwt"`. \*Token Type: `urn:ietf:params:oauth:token-type:access_token`\* 1. Confirm that the token is an access token that has been issued by the Authlete server of your service. This implies that access tokens issued by other systems cannot be used as a subject token or an actor token with the token type `urn:ietf:params:oauth:token-type:access_token`. 2. Confirm that the access token has not expired. 3. Confirm that the access token belongs to the service. \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\* 1. Confirm that the token is a refresh token that has been issued by the Authlete server of your service. This implies that refresh tokens issued by other systems cannot be used as a subject token or an actor token with the token type `urn:ietf:params:oauth:token-type:refresh_token`. 2. Confirm that the refresh token has not expired. 3. Confirm that the refresh token belongs to the service. \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\* 1. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). 2. Check if the ID Token is encrypted and if it is encrypted, then (a) reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() tokenExchangeEncryptedJwtRejected} flag of the service is `true` or (b) skip remaining validation steps when the flag is `false`. Note that Authlete does not verify an encrypted ID Token because there is no standard way to obtain the key to decrypt the ID Token with in the context of token exchange where the client ID for the encrypted ID Token cannot be determined. This means that you must verify an encrypted ID Token by yourself when one is used as an input token with the token type `"urn:ietf:params:oauth:token-type:id_token"`. 3. Confirm that the ID Token contains the `exp` claim and the current time has not reached the time indicated by the claim. 4. Confirm that the ID Token contains the `iat` claim and the current time is equal to or after the time indicated by the claim. 5. Confirm that the current time is equal to or after the time indicated by the `nbf` claim if the ID Token contains the claim. 6. Confirm that the ID Token contains the `iss` claim and the value is a valid URI. In addition, confirm that the URI has the `https` scheme, no query component and no fragment component. 7. Confirm that the ID Token contains the `aud` claim and its value is a JSON string or an array of JSON strings. 8. Confirm that the value of the `nonce` claim is a JSON string if the ID Token contains the claim. 9. Check if the ID Token is signed and if it is not signed, then (a) reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() tokenExchangeUnsignedJwtRejected} flag of the service is `true` or (b) finish validation on the input token. 10. Confirm that the signature algorithm is asymmetric. This implies that ID Tokens whose signature algorithm is symmetric (`HS256`, `HS384` or `HS512`) cannot be used as a subject token or an actor token with the token type `urn:ietf:params:oauth:token-type:id_token`. 11. Verify the signature of the ID Token. Signature verification is performed even in the case where the issuer of the ID Token is not your service. But in that case, the issuer must support the discovery endpoint defined in [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, signature verification fails. \*Token Type: `urn:ietf:params:oauth:token-type:saml1`\* (Authlete does not perform any validation for this token type.) \*Token Type: `urn:ietf:params:oauth:token-type:saml2`\* (Authlete does not perform any validation for this token type.) The specification of Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693.html)) is very flexible. In other words, the specification has abandoned the task of determining details. Therefore, for secure token exchange, you have to complement the specification with your own rules. For that purpose, Authlete provides some configuration options as listed below. Authorization server implementers may utilize them and/or implement their own rules. In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link #getResponseContent()} method returns `null`. You have to construct the token response by yourself. For example, you may generate an access token by calling Authlete''s `/api/auth/token/create` API and construct a token response like below. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: {challenge} Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-cache, no-store { "access_token": "{@link TokenCreateResponse#getAccessToken()}", "issued_token_type": "urn:ietf:params:oauth:token-type:access_token", "token_type": "Bearer", "expires_in": { @link TokenCreateResponse#getExpiresIn() }, "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" } ``` ## JWT_BEARER JWT_BEARER (Authlete 2.3 onwards) When the value of `"action"` is `"JWT_BEARER"`, it means that the request from the client application is a valid token request with the grant type `"urn:ietf:params:oauth:grant-type:jwt-bearer"` ([RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://www.rfc-editor.org/rfc/rfc7523.html)) and that the request has already passed the following validation steps. 1. Confirm that the `assertion` request parameter is given and its value is not empty. 2. Confirm that the format of the assertion conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). 3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token request when the {@link Service#isJwtGrantEncryptedJwtRejected() jwtGrantEncryptedJwtRejected} flag of the service is `true` or (b) skip remaining validation steps when the flag is `false`. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself. 4. Confirm that the JWT contains the `iss` claim and its value is a JSON string. 5. Confirm that the JWT contains the `sub` claim and its value is a JSON string. 6. Confirm that the JWT contains the `aud` claim and its value is either a JSON string or an array of JSON strings. 7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()}) or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()}) is listed as audience in the `aud` claim. 8. Confirm that the JWT contains the `exp` claim and the current time has not reached the time indicated by the claim. 9. Confirm that the current time is equal to or after the time indicated by by the `iat` claim if the JWT contains the claim. 10. Confirm that the current time is equal to or after the time indicated by by the `nbf` claim if the JWT contains the claim. 11. Check if the JWT is signed and if it is not signed, then (a) reject the token request when the {@link Service#isJwtGrantUnsignedJwtRejected() jwtGrantUnsignedJwtRejected} flag of the service is `true` or (b) finish validation on the JWT. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself. Authlete provides some configuration options for the grant type as listed below. Authorization server implementers may utilize them and/or implement their own rules. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-cache, no-store { "access_token": "{@link TokenCreateResponse#getAccessToken()}", "token_type": "Bearer", "expires_in": {@link TokenCreateResponse#getExpiresIn()}, "scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})" } ``` Finally, note again that Authlete does not verify the signature of the JWT specified by the `assertion` request parameter. You must verify the signature by yourself. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_request' example: parameters: grant_type=authorization_code&code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk clientId: '26478243745571' clientSecret: gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_request' responses: '200': description: Token operation completed successfully content: application/json: schema: $ref: '#/components/schemas/token_response' example: resultCode: A050001 resultMessage: '[A050001] The token request (grant_type=authorization_code) was processed successfully.' accessToken: C4SrUTijIj2IxqE1xBASr3dxQWgso3BpY49g8CyjGjQ accessTokenDuration: 3600 accessTokenExpiresAt: 1640252942736 action: OK clientAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value clientId: 26478243745571 clientIdAlias: my-client clientIdAliasUsed: false grantType: AUTHORIZATION_CODE refreshToken: 60k0cZ38sJcpTgdxvG9Sqa-3RG5AmGExGpFB-1imSxo refreshTokenDuration: 3600 refreshTokenExpiresAt: 1640252942736 responseContent: '{\"access_token\":\"C4SrUTijIj2IxqE1xBASr3dxQWgso3BpY49g8CyjGjQ\",\"refresh_token\":\"60k0cZ38sJcpTgdxvG9Sqa-3RG5AmGExGpFB-1imSxo\",\"scope\":\"history.read timeline.read\",\"token_type\":\"Bearer\",\"expires_in\":3600}' scopes: - history.read - timeline.read serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value subject: john '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "parameters": "grant_type=authorization_code&code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&redirect_uri=https%3A%2F%2Fmy-client.example.com%2Fcb1&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "clientId": "57297408867", "clientSecret": "J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenRequest req = new TokenRequest(); req.setParameters(...); req.setClientId("57297408867"); req.setClientSecret("J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A"); api.token(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = TokenRequest() req.parameters = ... req.clientId = ''57297408867'' req.clientSecret = ''J_3C7P0nDTP7CwCg_HyPQh7bTQ1696CC8GWot-EjesZmdBiU5Gsidq5Ve3tMaN2x2_VcKV1UE1U3ZdGKRuTs7A'' api.token(req) ' tags: - Token Endpoint /api/{serviceId}/auth/token/fail: post: summary: Fail Token Request description: 'This API generates a content of an error token response that the authorization server implementation returns to the client application. ' x-mint: metadata: description: This API generates a content of an error token response that the authorization server implementation returns to the client application. content: ' This API is supposed to be called from within the implementation of the token endpoint of the service in order to generate an error response to the client application. The description of the `/auth/token` API describes the timing when this API should be called. See the description for the case of `action=PASSWORD`. The response from `/auth/token/fail` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". 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 Authlete''s `/auth/token/fail` API successfully generated an error response for the client application. The HTTP status of the response returned to the client application must be "400 Bad Request" and the content type must be `application/json`. The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_fail_request' example: ticket: 83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c reason: INVALID_RESOURCE_OWNER_CREDENTIALS application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_fail_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/token_fail_response' example: resultCode: A067301 resultMessage: '[A067301] The credentials (username & password) passed to the token endpoint are invalid.' action: BAD_REQUEST responseContent: '{\"error_description\":\"[A067301] The credentials (username & password) passed to the token endpoint are invalid.\",\"error\":\"invalid_request\",\"error_uri\":\"https://docs.authlete.com/#A067301\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_fail_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/fail \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c", "reason": "INVALID_RESOURCE_OWNER_CREDENTIALS" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenFailRequest req = new TokenFailRequest(); req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c"); req.setReason(TokenFailRequest.Reason.INVALID_RESOURCE_OWNER_CREDENTIALS); api.tokenFail(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = TokenFailRequest() req.ticket = ''83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c'' req.reason = TokenFailReason.INVALID_RESOURCE_OWNER_CREDENTIALS api.tokenFail(req) ' tags: - Token Endpoint /api/{serviceId}/auth/token/issue: post: summary: Issue Token Response description: 'This API generates a content of a successful token response that the authorization server implementation returns to the client application. ' x-mint: metadata: description: This API generates a content of a successful token response that the authorization server implementation returns to the client application. content: ' This API is supposed to be called from within the implementation of the token endpoint of the service in order to generate a successful response to the client application. The description of the `/auth/token` API describes the timing when this API should be called. See the description for the case of `action=PASSWORD`. The response from `/auth/token/issue` API has some parameters. Among them, it is `action` parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of `action`, the authorization server implementation must take the steps described below. ## INTERNAL_SERVER_ERROR When the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". The value of `responseContent` is a JSON string which describes the error, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation should generate and return to the client application. ``` HTTP/1.1 500 Internal Server Error Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. ## OK When the value of `action` is `OK`, it means that Authlete''s `/auth/token/issue` API successfully generated an access token. The HTTP status of the response returned to the client application must be "200 OK" and the content type must be`application/json`. The value of `responseContent` is a JSON string which contains an access token, so it can be used as the entity body of the response. --- The following illustrates the response which the service implementation must generate and return to the client application. ``` HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {responseContent} ``` ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/token_issue_request' example: ticket: p7SXQ9JFjng7KFOZdCMBKcoR3ift7B54l1LGIgQXqEM subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/token_issue_request' responses: '200': description: Token issued successfully content: application/json: schema: $ref: '#/components/schemas/token_issue_response' example: resultCode: A054001 resultMessage: '[A054001] The token request (grant_type=password) was processed successfully.' accessToken: OthV6TlZ2pPUtlBBvBSGFYzSdgVy87SSIPz2Zjwi-m0 accessTokenDuration: 3600 accessTokenExpiresAt: 1640331371876 action: OK clientAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value clientId: 26478243745571 clientIdAlias: my-client clientIdAliasUsed: false refreshToken: ICPN0-sG3BH4szqiNqaFHZrWUGt7e0zaPuhys3ejQow refreshTokenDuration: 3600 refreshTokenExpiresAt: 1640331371876 responseContent: '{\"access_token\":\"OthV6TlZ2pPUtlBBvBSGFYzSdgVy87SSIPz2Zjwi-m0\",\"refresh_token\":\"ICPN0-sG3BH4szqiNqaFHZrWUGt7e0zaPuhys3ejQow\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":3600}' serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value subject: john '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: auth_token_issue_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/auth/token/issue \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "p7SXQ9JFjng7KFOZdCMBKcoR3ift7B54l1LGIgQXqEM", "subject": "john" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); TokenIssueRequest req = new TokenIssueRequest() req.setTicket("83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c"); api.tokenIssue(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = TokenIssueRequest() req.ticket = ''83BNqKIhGMyrkvop_7jQjv2Z1612LNdGSQKkvkrf47c'' api.tokenIssue(req) ' tags: - Token Endpoint /api/{serviceId}/idtoken/reissue: post: summary: Reissue ID Token description: 'The API is expected to be called only when the value of the `action` parameter in a response from the `/auth/token` API is [ID_TOKEN_REISSUABLE](https://authlete.github.io/authlete-java-common/com/authlete/common/dto/TokenResponse.Action.html#ID_TOKEN_REISSUABLE). The purpose of the `/idtoken/reissue` API is to generate a token response that includes a new ID token together with a new access token and a refresh token. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/idtoken_reissue_request' responses: '200': description: ID token reissued successfully content: application/json: schema: $ref: '#/components/schemas/idtoken_reissue_response' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: idtoken_reissue_api tags: - Token Endpoint components: schemas: token_issue_request: type: object required: - ticket - subject properties: ticket: type: string description: 'The ticket issued from Authlete `/auth/token` API. ' subject: type: string description: 'The subject (= unique identifier) of the authenticated user. ' properties: type: array items: $ref: '#/components/schemas/property' description: 'Extra properties to associate with a newly created access token. 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` if you want to specify properties. ' jwtAtClaims: type: string description: 'Additional claims that are added to the payload part of the JWT access token. ' accessToken: type: string description: 'The representation of an access token that may be issued as a result of the Authlete API call. ' accessTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. ' refreshTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. ' token_issue_response: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. action: type: string enum: - INTERNAL_SERVER_ERROR - OK description: The next action that the authorization server implementation should take. responseContent: type: string description: 'The content that the authorization server implementation is to return to the client application. Its format is JSON. ' accessToken: type: string description: The newly issued access token. This parameter is a non-null value only when the value of `action` parameter is `OK`. accessTokenExpiresAt: type: integer format: int64 description: 'The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). ' accessTokenDuration: type: integer format: int64 description: The duration of the newly issued access token in seconds. refreshToken: type: string description: 'The refresh token. This parameter is a non-null value only when `action` is `OK` and the service supports the refresh token flow. If `refreshTokenKept` is set to `false`, a new refresh token is issued and the old refresh token used in the refresh token flow is invalidated. On the contrary, if `refreshTokenKept` is set to `true`, the refresh token itself is not refreshed. ' refreshTokenExpiresAt: type: integer format: int64 description: 'The datetime at which the newly issued refresh token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). ' refreshTokenDuration: type: integer format: int64 description: The duration of the newly issued refresh token in seconds. clientId: type: integer format: int64 description: The client ID. clientIdAlias: type: string description: 'The client ID alias. If the client did not have an alias, 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. ' subject: type: string description: 'The subject (= resource owner''s ID) of the access token. Even if an access token has been issued by calling `/api/auth/token` API, this parameter is `null` if the flow of the token request was [Client Credentials Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) (`grant_type=client_credentials`) because it means the access token is not associated with any specific end-user. ' scopes: type: array items: type: string description: The scopes covered by the access token. properties: type: array items: $ref: '#/components/schemas/property' description: 'The extra properties associated with the access token. This parameter is `null` when no extra property is associated with the issued access token. ' jwtAccessToken: type: string description: 'The newly issued access token in JWT format. If the authorization server is configured to issue JWT-based access tokens (= if the service''s `accessTokenSignAlg` value is a non-null value), a JWT-based access token is issued along with the original random-string one. ' accessTokenResources: type: array items: type: string description: 'The target resources of the access token being issued. 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. ' 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. ' refreshTokenScopes: type: array items: type: string description: 'The scopes associated with the refresh token. May be null. ' 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. ' token_info: type: object properties: clientId: type: integer description: The client id. clientIdAlias: type: string description: The alias of the client. clientIdAliasUsed: type: boolean description: Flag specifying if the alias was used to identify the client subject: type: string description: the resource owner unique id scopes: type: array items: $ref: '#/components/schemas/scope' description: The scopes granted on the token expiresAt: type: integer description: time which the token expires. properties: type: array description: Extra properties associated with the token items: $ref: '#/components/schemas/property' resources: type: array description: The array of the resources of the token. items: type: string authorizationDetails: $ref: '#/components/schemas/authorization_details_element' clientEntityId: type: string description: 'The entity ID of the client. ' clientEntityIdUsed: type: boolean description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made. ' metadataDocumentLocation: type: string format: uri description: 'The location of the client''s metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. ' metadataDocumentUsed: type: boolean description: 'Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ' idtoken_reissue_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: - OK - INTERNAL_SERVER_ERROR - CALLER_ERROR description: The next action that the implementation of the token endpoint should take. responseContent: type: string description: 'The response content that can be used as the message body of the token response that should be returned from the token endpoint. ' idToken: type: string description: 'The reissued ID token ' tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. token_fail_response: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. action: type: string enum: - INTERNAL_SERVER_ERROR - BAD_REQUEST description: The next action that the authorization server implementation should take. responseContent: type: string description: 'The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. See description for 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. ' token_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 - INVALID_CLIENT - BAD_REQUEST - PASSWORD - OK - TOKEN_EXCHANGE - JWT_BEARER - NATIVE_SSO - ID_TOKEN_REISSUABLE description: The next action that the authorization server implementation should take. responseContent: type: string description: 'The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of `action` parameter. ' username: type: string description: 'The value of `username` request parameter in the token request. The client application must specify username when it uses [Resource Owner Password Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3). In other words, when the value of `grant_type` request parameter is `password`, `username` request parameter must come along. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. ' password: type: string description: 'The value of `password` request parameter in the token request. The client application must specify password when it uses [Resource Owner Password Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3). In other words, when the value of `grant_type` request parameter is `password`, `password` request parameter must come along. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. ' ticket: type: string description: 'The ticket which is necessary to call Authlete''s `/auth/token/fail` API or `/auth/token/issue` API. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. ' accessToken: type: string description: The newly issued access token. accessTokenExpiresAt: type: integer format: int64 description: 'The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). ' accessTokenDuration: type: integer format: int64 description: The duration of the newly issued access token in seconds. refreshToken: type: string description: The newly issued refresh token. refreshTokenExpiresAt: type: integer format: int64 description: 'The datetime at which the newly issued refresh token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). ' refreshTokenDuration: type: integer format: int64 description: The duration of the newly issued refresh token in seconds. idToken: type: string description: 'The newly issued ID token. Note that an ID token is issued from a token endpoint only when the `response_type` request parameter of the authorization request to an authorization endpoint has contained `code` and the `scope` request parameter has contained `openid`. ' grantType: type: string description: The grant type of the token request. 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. ' subject: type: string description: 'The subject (= resource owner''s ID) of the access token. Even if an access token has been issued by the call of `/api/auth/token` API, this parameter is `null` if the flow of the token request was [Client Credentials Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) (`grant_type=client_credentials`) because it means the access token is not associated with any specific end-user. ' scopes: type: array items: type: string description: The scopes covered by the access token. properties: type: array items: $ref: '#/components/schemas/property' description: 'The extra properties associated with the access token. This parameter is `null` when no extra property is associated with the issued access token. ' jwtAccessToken: type: string description: 'The newly issued access token in JWT format. If the authorization server is configured to issue JWT-based access tokens (= if the service''s `accessTokenSignAlg` value is a non-null value), a JWT-based access token is issued along with the original random-string one. ' 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. ' accessTokenResources: type: array items: type: string description: 'The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details. ' authorizationDetails: $ref: '#/components/schemas/authz_details' additionalClaims: type: string description: 'Additional claims to be embedded in an ID token. ' 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. ' clientAuthMethod: type: string description: 'The client authentication method that was performed at the token endpoint. ' 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. ' audiences: type: array items: type: string description: 'The audiences on the token exchange request ' requestedTokenType: $ref: '#/components/schemas/token_type' subjectToken: type: string subjectTokenType: $ref: '#/components/schemas/token_type' subjectTokenInfo: $ref: '#/components/schemas/token_info' actorToken: type: string actorTokenType: $ref: '#/components/schemas/token_type' actorTokenInfo: $ref: '#/components/schemas/token_info' assertion: type: string description: 'For RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants ' previousRefreshTokenUsed: type: boolean description: 'Indicate whether the previous refresh token that had been kept in the database for a short time was used ' 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. ' cnonceDuration: type: integer format: int64 description: 'Duration of the `c_nonce` in seconds. ' dpopNonce: type: string description: 'Get the expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. ' cnonce: type: string description: 'Get the `c_nonce`. ' cnonceExpiresAt: type: integer format: int64 description: 'Get the time at which the `c_nonce` expires in milliseconds since the Unix epoch (1970-01-01). ' requestedIdTokenClaims: type: array items: type: string description: 'Get the names of the claims that the authorization request (which resulted in generation of the access token) requested to be embedded in ID tokens. ' refreshTokenScopes: type: array items: type: string description: 'Scopes associated with the refresh token. ' sessionId: type: string description: 'The session ID, which is the ID of the user''s authentication session, associated with a newly created access token. ' deviceSecret: type: string description: 'If the response from the `/auth/token` API contains the `deviceSecret` parameter, its value should be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value. ' x-mint: metadata: description: If the response from the `/auth/token` API contains the `deviceSecret` parameter, its value should be used as the value of this `deviceSecret` request parameter to the `/nativesso` API. The authorization server may choose to issue a new device secret; in that case, it is free to generate a new device secret and specify the new value. content: ' If the response from the `/auth/token` API does not contain the `deviceSecret` parameter, or if its value is invalid, the authorization server must generate a new device secret and specify it in the deviceSecret parameter to the `/nativesso` API. The specified value is used as the value of the `device_secret` property in the token response. ' deviceSecretHash: type: string description: 'The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API. ' x-mint: metadata: description: The authorization server should compute the hash value of the device secret based on its own logic and specify the computed hash as the value of this `deviceSecretHash` request parameter to the `/nativesso` API. content: ' When the `deviceSecretHash` parameter is omitted, the implementation of the `/nativesso` API generates the device secret hash by computing the SHA-256 hash of the device secret and encoding it with base64url. Note that this hash computation logic is not a rule defined in the Native SSO specification; rather, it is Authlete-specific fallback logic used when the `deviceSecretHash` parameter is omitted. ' metadataDocumentLocation: type: string format: uri description: 'The location of the client''s metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. ' metadataDocumentUsed: type: boolean description: 'Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ' authz_details: type: object description: 'The authorization details. This represents the value of the `authorization_details` request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests". ' properties: elements: type: array items: $ref: '#/components/schemas/authorization_details_element' description: 'Elements of this authorization details. ' authorization_details_element: type: object required: - type properties: type: type: string description: 'The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. ' locations: type: array items: type: string description: 'The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. ' actions: type: array items: type: string description: 'The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. ' dataTypes: type: array items: type: string description: 'From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. ' identifier: type: string description: 'The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. ' privileges: type: array items: type: string description: 'The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. ' otherFields: type: string description: 'The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. ' result: type: object properties: resultCode: type: string description: The code which represents the result of the API call. resultMessage: type: string description: A short message which explains the result of the API call. scope: type: object properties: name: type: string description: The name of the scope. defaultEntry: type: boolean description: '`true` to mark the scope as default. Scopes marked as default are regarded as requested when an authorization request from a client application does not contain scope request parameter. ' description: type: string description: The description about the scope. descriptions: type: array description: The descriptions about this scope in multiple languages. items: $ref: '#/components/schemas/tagged_value' attributes: type: array description: The attributes of the scope. items: $ref: '#/components/schemas/pair' pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. cimd_options: type: object description: 'Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. ' properties: alwaysRetrieved: type: boolean description: 'Whether to always retrieve client metadata in the CIMD context regardless of the cache''s validity. Under normal circumstances, client metadata retrieved from the location referenced by the client ID is stored in the database with an expiration time calculated using HTTP caching mechanisms (see [RFC 9111 HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html)). Until that expiration time is reached, Authlete does not attempt to retrieve the client metadata again. When this flag is set to `true`, Authlete retrieves the client metadata regardless of the cache''s validity. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdAlwaysRetrieved`). This flag is effective only when the service supports CIMD (see `Service.clientIdMetadataDocumentSupported`) and CIMD is actually used to resolve client metadata. For example, if the client ID in a request does not appear to be a valid URI, CIMD will not be used even if the service is configured to support it. In such cases, this flag has no effect. Client metadata retrieval is performed only in the initiating request of an authorization flow, and not in any subsequent requests. For example, in the authorization code flow, metadata may be retrieved during the authorization request, but not during the subsequent token request. In contrast, in the client credentials flow, metadata retrieval may occur because the token request itself is the initiating request in the flow. ' httpPermitted: type: boolean description: 'Whether to allow the `http` scheme in client IDs in the CIMD context. The specification requires the `https` scheme, but if this flag is set to `true`, Authlete also allows the `http` scheme. The main purpose of this option is to make development easier for developers who run CIMD-enabled servers and a web server publishing client metadata on their local machines without TLS. Given this purpose, it is not recommended to enable this option in production environments unless an allowlist is used (see `Service.cimdAllowlistEnabled`). If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdHttpPermitted`). ' queryPermitted: type: boolean description: 'Whether to allow a query component in client IDs in the CIMD context. Although the specification states that a client ID "SHOULD NOT include a query string component," it does technically allow it. However, query components are prone to misuse. Therefore, Authlete does not allow them by default. Setting this flag to `true` relaxes that restriction. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdQueryPermitted`). ' token_type: type: string description: 'The token type identifier used in OAuth 2.0 Token Exchange (RFC 8693). The API returns short codes (enum constant names) in response fields. ' enum: - JWT - ACCESS_TOKEN - REFRESH_TOKEN - ID_TOKEN - SAML1 - SAML2 - DEVICE_SECRET - DEVICE_CODE - TOKEN_EXCHANGE - JWT_BEARER token_request: type: object required: - parameters properties: parameters: type: string description: 'OAuth 2.0 token request parameters which are the request parameters that the OAuth 2.0 token endpoint of the authorization server implementation received from the client application. The value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the request from the client application. ' clientId: type: string description: 'The client ID extracted from `Authorization` header of the token request from the client application. If the token endpoint of the authorization server implementation supports basic authentication as a means of client authentication, and the request from the client application contained its client ID in `Authorization` header, the value should be extracted and set to this parameter. ' clientSecret: type: string description: 'The client secret extracted from `Authorization` header of the token request from the client application. If the token endpoint of the authorization server implementation supports basic authentication as a means of client authentication, and the request from the client application contained its client secret in `Authorization` header, the value should be extracted and set to this parameter. ' clientCertificate: type: string description: The client certificate from the MTLS of the token request from the client application. clientCertificatePath: type: array items: type: string description: 'The certificate path presented by the client during client authentication. These certificates are strings in PEM format. ' properties: type: array description: 'Extra properties to associate with an access token. See [Extra Properties](https://www.authlete.com/developers/definitive_guide/extra_properties/) for details. ' items: $ref: '#/components/schemas/property' dpop: type: string description: '`DPoP` header presented by the client during the request to the token endpoint. The header contains a signed JWT which includes the public key that is paired with the private key used to sign the JWT. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. ' htm: type: string description: 'HTTP method of the token request. This field is used to validate the `DPoP` header. In normal cases, the value is `POST`. When this parameter is omitted, `POST` is used as the default value. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. ' htu: type: string description: 'URL of the token endpoint. This field is used to validate the `DPoP` header. If this parameter is omitted, the `tokenEndpoint` property of the Service is used as the default value. See [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop) for details. ' accessToken: type: string description: 'The representation of an access token that may be issued as a result of the Authlete API call. ' jwtAtClaims: type: string description: 'Additional claims that are added to the payload part of the JWT access token. ' oauthClientAttestation: type: string description: 'The value of the `OAuth-Client-Attestation` HTTP header, which is defined in the specification of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/). ' oauthClientAttestationPop: type: string description: 'The value of the `OAuth-Client-Attestation-PoP` HTTP header, which is defined in the specification of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/). ' accessTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. ' refreshTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the refresh token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the refresh token in. In other cases, this request parameter is ignored. ' dpopNonceRequired: type: boolean description: 'The flag indicating whether to require the DPoP proof JWT to include the `nonce` claim. Even if the service''s `dpopNonceRequired` property is `false`, calling the `/auth/token` API with this `dpopNonceRequired` parameter `true` will force the Authlete API to check whether the DPoP proof JWT includes the expected `nonce` value. ' 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. ' idtoken_reissue_request: type: object required: - accessToken - refreshToken properties: accessToken: type: string description: 'The value of this parameter should be (a) the value of the "`jwtAccessToken`" parameter in a response from the `/auth/token` API when the value is available, or (b) the value of the "`accessToken`" parameter in the response from the `/auth/token` API when the value of the "`jwtAccessToken`" parameter is not available. ' refreshToken: type: string description: 'The value of this parameter should be the value of the "`refreshToken`" parameter in a response from the `/auth/token` API. ' sub: type: string description: 'The value that should be used as the value of the "`sub`" claim of the ID token. This parameter is optional. When omitted, the value of the subject associated with the access token is used. ' claims: type: string description: 'Additional claims that should be embedded in the payload part of the ID token. The format is a JSON object. This parameter is optional. ' idtHeaderParams: type: string description: 'Additional parameters that should be embedded in the JWS header of the ID token. The format is a JSON object. This parameter is optional. ' idTokenAudType: type: string description: 'The type of the "`aud`" claim of the ID token being issued. Valid values of this parameter are as follows. > | Value | Description | > | --- | --- | > | "`array`" | The type of the `aud` claim becomes an array of strings. | > | "`string`" | The type of the `aud` claim becomes a single string. | This parameter is optional, and the default value on omission is "`array`". This parameter takes precedence over the `idTokenAudType` property of {@link Service} (cf. {@link Service#getIdTokenAudType()}). ' token_fail_request: type: object required: - ticket - reason properties: ticket: type: string description: 'The ticket issued from Authlete `/auth/token` API. ' reason: type: string enum: - UNKNOWN - INVALID_RESOURCE_OWNER_CREDENTIALS - INVALID_TARGET description: 'The reason of the failure of the token request. ' responses: '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.' securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT description: 'Authenticate every request with a **Service Access Token** or **Organization Token**. Set the token value in the `Authorization: Bearer ` header. **Service Access Token**: Scoped to a single service. Use when automating service-level configuration or runtime flows. **Organization Token**: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically. Both token types are issued by the Authlete console or provisioning APIs. '