> ## Documentation Index > Fetch the complete documentation index at: https://developers.authlete.com/llms.txt > Use this file to discover all available pages before exploring further. # Process Token Request > This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. This API is supposed to be called from 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](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. 5. 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`\* 6. 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`. 7. Confirm that the access token has not expired. 8. Confirm that the access token belongs to the service. \*Token Type: `urn:ietf:params:oauth:token-type:refresh_token`\* 9. 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`. 10. Confirm that the refresh token has not expired. 11. Confirm that the refresh token belongs to the service. \*Token Type: `urn:ietf:params:oauth:token-type:id_token`\* 12. Confirm that the format conforms to the JWT specification ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519.html)). 13. 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"`. 14. Confirm that the ID Token contains the `exp` claim and the current time has not reached the time indicated by the claim. 15. Confirm that the ID Token contains the `iat` claim and the current time is equal to or after the time indicated by the claim. 16. Confirm that the current time is equal to or after the time indicated by the `nbf` claim if the ID Token contains the claim. 17. 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. 18. Confirm that the ID Token contains the `aud` claim and its value is a JSON string or an array of JSON strings. 19. Confirm that the value of the `nonce` claim is a JSON string if the ID Token contains the claim. 20. 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. 21. 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`. 22. 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. ## OpenAPI ````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/auth/token openapi: 3.0.3 info: title: Authlete API description: '' version: 3.0.16 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - description: πŸ‡ΊπŸ‡Έ US Cluster url: https://us.authlete.com - description: πŸ‡―πŸ‡΅ Japan Cluster url: https://jp.authlete.com - description: πŸ‡ͺπŸ‡Ί Europe Cluster url: https://eu.authlete.com - description: πŸ‡§πŸ‡· Brazil Cluster url: https://br.authlete.com security: - bearer: [] tags: - name: Service Management description: >- API endpoints for managing services, including creation, update, and deletion of services. x-tag-expanded: false - name: Client Management description: >- API endpoints for managing OAuth clients, including creation, update, and deletion of clients. x-tag-expanded: false - name: Authorization Endpoint description: API endpoints for implementing OAuth 2.0 Authorization Endpoint. x-tag-expanded: false - name: Pushed Authorization Endpoint description: >- API endpoints for implementing OAuth 2.0 Pushed Authorization Requests (PAR). x-tag-expanded: false - name: Token Endpoint description: API endpoints for implementing OAuth 2.0 Token Endpoint. x-tag-expanded: false - name: Token Operations description: >- API endpoints for various token related operations, including creating, revoking and deleting access_tokens with specified scopes. x-tag-expanded: false - name: Introspection Endpoint description: API endpoints for implementing OAuth 2.0 Introspection Endpoint. x-tag-expanded: false - name: Revocation Endpoint description: API endpoint for implementing OAuth 2.0 Revocation Endpoint. x-tag-expanded: false - name: UserInfo Endpoint description: API endpoints for implementing OpenID Connect UserInfo Endpoint. x-tag-expanded: false - name: JWK Set Endpoint description: API endpoints for to generate JSON Web Key Set (JWKS) for a service. x-tag-expanded: false - name: Discovery Endpoint description: API endpoints for implementing OpenID Connect Discovery. x-tag-expanded: false - name: Configuration Endpoint description: API endpoint for accessing configuration settings for a service. x-tag-expanded: false - name: Dynamic Client Registration description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration. x-tag-expanded: false - name: CIBA description: >- API endpoints for implementing Client-Initiated Backchannel Authentication (CIBA). x-tag-expanded: false - name: Grant Management Endpoint description: >- API endpoint for implementing OAuth 2.0 grants, including grant management actions like updating and revoking grants. x-tag-expanded: false - name: Jose Object description: API endpoints for JOSE objects. x-tag-expanded: false - name: Device Flow description: API endpoints for implementing OAuth 2.0 Device Flow x-tag-expanded: false - name: Federation Endpoint description: API endpoints for implementing OpenID Federation using Authlete. x-tag-expanded: false - name: Verifiable Credential Issuer description: >- API endpoints for implementing and running a Verifiable Credential Issuer (VCI). x-tag-expanded: false - name: Hardware Security Key description: API endpoints for managing hardware security keys (HSK). x-tag-expanded: false - name: Utility Endpoints description: API endpoints for various utility operations. x-tag-expanded: false - name: Native SSO description: API endpoints for Native SSO x-tag-expanded: false paths: /api/{serviceId}/auth/token: post: tags: - Token Endpoint 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. operationId: auth_token_api parameters: - in: path name: serviceId description: A service ID. schema: type: string required: true requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/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' x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Authlete } from "@authlete/typescript-sdk"; const authlete = new Authlete({ bearer: process.env["AUTHLETE_BEARER"] ?? "", }); async function run() { const result = await authlete.token.process({ serviceId: "", tokenRequest: { 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", }, }); console.log(result); } run(); - lang: ruby label: Ruby (SDK) source: >- require 'authlete_ruby_sdk' Models = ::Authlete::Models s = ::Authlete::Client.new( bearer: '' ) res = s.tokens.process_request(service_id: '', token_request: Models::Components::TokenRequest.new( 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', client_id: '26478243745571', client_secret: 'gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ' )) unless res.token_response.nil? # handle response end - lang: go label: Go (SDK) source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tauthlete \"github.com/authlete/authlete-go-sdk\"\n\t\"github.com/authlete/authlete-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := authlete.New(\n authlete.WithSecurity(os.Getenv(\"AUTHLETE_BEARER\")),\n )\n\n res, err := s.Token.Process(ctx, \"\", components.TokenRequest{\n 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\",\n ClientID: authlete.Pointer(\"26478243745571\"),\n ClientSecret: authlete.Pointer(\"gXz97ISgLs4HuXwOZWch8GEmgL4YMvUJwu3er_kDVVGcA0UOhA9avLPbEmoeZdagi9yC_-tEiT2BdRyH9dbrQQ\"),\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.TokenResponse != nil {\n // handle response\n }\n}" x-code-samples: - lang: shell label: curl source: > curl -v -X POST https://us.authlete.com/api/21653835348762/auth/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) components: schemas: 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. 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. 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. 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`). 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. pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. 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_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. 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. 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. 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' tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. responses: '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: >- [A001215] /auth/authorization, The client (ID = 26837717140341) is locked. '500': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001101 resultMessage: '[A001101] /auth/authorization, Authlete Server error.' securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT description: > Authenticate every request with a **Service Access Token** or **Organization Token**. Set the token value in the `Authorization: Bearer ` header. **Service Access Token**: Scoped to a single service. Use when automating service-level configuration or runtime flows. **Organization Token**: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically. Both token types are issued by the Authlete console or provisioning APIs. ````