--- title: "Process Token Request" method: POST path: "/api/{serviceId}/auth/token" tags: ["Token Endpoint"] --- # Process Token Request `POST /api/{serviceId}/auth/token` This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. ### Description 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. ## Path parameters - `serviceId` string, required ## Request body - TokenRequest - `parameters` string, required — 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` string — 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` string — 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` string — The client certificate from the MTLS of the token request from the client application. - `clientCertificatePath` string[] — The certificate path presented by the client during client authentication. These certificates are strings in PEM format. - `properties` string — Extra properties to associate with an access token. See [Extra Properties](https://www.authlete.com/developers/definitive_guide/extra_properties/) for details. - `dpop` string — `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` string — 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` string — 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` string — The representation of an access token that may be issued as a result of the Authlete API call. - `jwtAtClaims` string — Additional claims that are added to the payload part of the JWT access token. - `oauthClientAttestation` string — 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` string — 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` integer — 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` integer — 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` boolean — 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` CimdOptions — 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. - `alwaysRetrieved` boolean — 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` boolean — 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` boolean — 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`). ## Response `200` Token operation completed successfully - TokenResponse - `resultCode` string — The code which represents the result of the API call. - `resultMessage` string — A short message which explains the result of the API call. - `action` 'INTERNAL_SERVER_ERROR' | 'INVALID_CLIENT' | 'BAD_REQUEST' | 'PASSWORD' | 'OK' | 'TOKEN_EXCHANGE' | 'JWT_BEARER' | 'NATIVE_SSO' | 'ID_TOKEN_REISSUABLE' — The next action that the authorization server implementation should take. - `responseContent` string — 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` string — 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` string — 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` string — 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` string — The newly issued access token. - `accessTokenExpiresAt` integer — 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` integer — The duration of the newly issued access token in seconds. - `refreshToken` string — The newly issued refresh token. - `refreshTokenExpiresAt` integer — 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` integer — The duration of the newly issued refresh token in seconds. - `idToken` string — 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` string — The grant type of the token request. - `clientId` integer — The client ID. - `clientIdAlias` string — 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` boolean — 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` string — 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` string[] — The scopes covered by the access token. - `properties` Property[] — The extra properties associated with the access token. This parameter is `null` when no extra property is associated with the issued access token. - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — 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. - `jwtAccessToken` string — 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` string[] — The resources specified by the `resource` request parameters in the token request. See "Resource Indicators for OAuth 2.0" for details. - `accessTokenResources` string[] — The target resources of the access token being issued. See "Resource Indicators for OAuth 2.0" for details. - `authorizationDetails` AuthzDetails — 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". - `elements` AuthorizationDetailsElement[] — Elements of this authorization details. - `type` string, required — 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` string[] — 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` string[] — 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` string[] — 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` string — 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` string[] — 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` string — 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. - `additionalClaims` string — Additional claims to be embedded in an ID token. - `serviceAttributes` Pair[] — The attributes of this service that the client application belongs to. - `key` string — The key part. - `value` string — The value part. - `clientAttributes` Pair[] — The attributes of the client. - `key` string — The key part. - `value` string — The value part. - `clientAuthMethod` string — The client authentication method that was performed at the token endpoint. - `grantId` string — 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` string[] — The audiences on the token exchange request - `requestedTokenType` 'JWT' | 'ACCESS_TOKEN' | 'REFRESH_TOKEN' | 'ID_TOKEN' | 'SAML1' | 'SAML2' | 'DEVICE_SECRET' | 'DEVICE_CODE' | 'TOKEN_EXCHANGE' | 'JWT_BEARER' — The token type identifier used in OAuth 2.0 Token Exchange (RFC 8693). The API returns short codes (enum constant names) in response fields. - `subjectToken` string - `subjectTokenType` 'JWT' | 'ACCESS_TOKEN' | 'REFRESH_TOKEN' | 'ID_TOKEN' | 'SAML1' | 'SAML2' | 'DEVICE_SECRET' | 'DEVICE_CODE' | 'TOKEN_EXCHANGE' | 'JWT_BEARER' — The token type identifier used in OAuth 2.0 Token Exchange (RFC 8693). The API returns short codes (enum constant names) in response fields. - `subjectTokenInfo` TokenInfo - `clientId` integer — The client id. - `clientIdAlias` string — The alias of the client. - `clientIdAliasUsed` boolean — Flag specifying if the alias was used to identify the client - `subject` string — the resource owner unique id - `scopes` Scope[] — The scopes granted on the token - `name` string — The name of the scope. - `defaultEntry` boolean — `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` string — The description about the scope. - `descriptions` TaggedValue[] — The descriptions about this scope in multiple languages. - `tag` string — The language tag part. - `value` string — The value part. - `attributes` Pair[] — The attributes of the scope. - `key` string — The key part. - `value` string — The value part. - `expiresAt` integer — time which the token expires. - `properties` Property[] — Extra properties associated with the token - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — 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. - `resources` string[] — The array of the resources of the token. - `authorizationDetails` AuthorizationDetailsElement - `type` string, required — 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` string[] — 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` string[] — 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` string[] — 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` string — 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` string[] — 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` string — 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. - `clientEntityId` string — The entity ID of the client. - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made. - `metadataDocumentLocation` string, uri — 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` boolean — 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. - `actorToken` string - `actorTokenType` 'JWT' | 'ACCESS_TOKEN' | 'REFRESH_TOKEN' | 'ID_TOKEN' | 'SAML1' | 'SAML2' | 'DEVICE_SECRET' | 'DEVICE_CODE' | 'TOKEN_EXCHANGE' | 'JWT_BEARER' — The token type identifier used in OAuth 2.0 Token Exchange (RFC 8693). The API returns short codes (enum constant names) in response fields. - `actorTokenInfo` TokenInfo - `clientId` integer — The client id. - `clientIdAlias` string — The alias of the client. - `clientIdAliasUsed` boolean — Flag specifying if the alias was used to identify the client - `subject` string — the resource owner unique id - `scopes` Scope[] — The scopes granted on the token - `name` string — The name of the scope. - `defaultEntry` boolean — `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` string — The description about the scope. - `descriptions` TaggedValue[] — The descriptions about this scope in multiple languages. - `tag` string — The language tag part. - `value` string — The value part. - `attributes` Pair[] — The attributes of the scope. - `key` string — The key part. - `value` string — The value part. - `expiresAt` integer — time which the token expires. - `properties` Property[] — Extra properties associated with the token - `key` string — The key part. - `value` string — The value part. - `hidden` boolean — 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. - `resources` string[] — The array of the resources of the token. - `authorizationDetails` AuthorizationDetailsElement - `type` string, required — 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` string[] — 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` string[] — 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` string[] — 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` string — 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` string[] — 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` string — 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. - `clientEntityId` string — The entity ID of the client. - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made. - `metadataDocumentLocation` string, uri — 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` boolean — 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. - `assertion` string — For RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants - `previousRefreshTokenUsed` boolean — Indicate whether the previous refresh token that had been kept in the database for a short time was used - `clientEntityId` string — The entity ID of the client. - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made. - `cnonceDuration` integer — Duration of the `c_nonce` in seconds. - `dpopNonce` string — Get the expected nonce value for DPoP proof JWT, which should be used as the value of the `DPoP-Nonce` HTTP header. - `cnonce` string — Get the `c_nonce`. - `cnonceExpiresAt` integer — Get the time at which the `c_nonce` expires in milliseconds since the Unix epoch (1970-01-01). - `requestedIdTokenClaims` string[] — 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` string[] — Scopes associated with the refresh token. - `sessionId` string — The session ID, which is the ID of the user's authentication session, associated with a newly created access token. - `deviceSecret` string — 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. 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` string — 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. 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` string, uri — 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` boolean — 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. ## Other responses - `400` - `401` - `403` - `500` ## Changes - **2026-01-15** `8a534bc68775` — 2 breaking, 2 warning, 11 info - the `actorTokenInfo/scopes/items/` response's property type/format changed from `string`/`` to `object`/`` for status `200` - the `subjectTokenInfo/scopes/items/` response's property type/format changed from `string`/`` to `object`/`` for status `200` - added the new `ID_TOKEN_REISSUABLE` enum value to the `action` response property for the response status `200` - added the new `NATIVE_SSO` enum value to the `action` response property for the response status `200` - …11 more - **2025-12-18** `504771740022` — 8 info - added the new optional request property `cimdOptions` (media type: application/json) - added the new optional request property `cimdOptions` (media type: application/x-www-form-urlencoded) - added the optional property `actorTokenInfo/metadataDocumentLocation` to the response with the `200` status - added the optional property `actorTokenInfo/metadataDocumentUsed` to the response with the `200` status - …4 more [Change history](https://skmtc.dev/authlete/apis/authlete-api/changes/api/:serviceId/auth/token/post.md) --- [API](https://skmtc.dev/authlete/apis/authlete-api.md) · [All operations](https://skmtc.dev/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/authlete/authlete-api/revisions/8a534bc68775/schema)