--- 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. ## 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` Property[] — Extra properties to associate with an access token. See [Extra Properties](https://www.authlete.com/developers/definitive_guide/extra_properties/) for details. - `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. - `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. Effective only in the client_credentials grant flow (and the Native SSO branch of Token Exchange). For other grant flows, set additional JWT claims via the corresponding API: /auth/authorization/issue (authorization_code), /auth/backchannel/authentication/complete (CIBA), /auth/device/complete (device_code). The parameter is silently ignored when sent with other grants. - `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. - `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. - `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` - `429` — The request exceeded the request rate permitted for the endpoint. - `500` --- [API](https://skmtc.net/authlete/apis/authlete-api.md) · [All operations](https://skmtc.net/authlete/apis/authlete-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/authlete/authlete-api/versions/7ad74ab64749/schema)