---
title: "Issue Token Response"
method: POST
path: "/api/{serviceId}/auth/token/issue"
tags: ["Token Endpoint"]
---

# Issue Token Response

`POST /api/{serviceId}/auth/token/issue`

This API generates a content of a successful token response that the authorization server implementation
returns to the client application.
### Description
This API is supposed to be called from within the implementation of the token endpoint of the service
in order to generate a successful response to the client application.
The description of the `/auth/token` API describes the timing when this API should be called. See
the description for the case of `action=PASSWORD`.
The response from `/auth/token/issue` API has some parameters. Among them, it is `action` parameter
that the authorization server implementation should check first because it denotes the next action
that the authorization server implementation should take. According to the value of `action`, the
authorization server implementation must take the steps described below.
**INTERNAL\_SERVER\_ERROR**
When the value of `action` is `INTERNAL\_SERVER\_ERROR`, it means that the request from the authorization
server implementation was wrong or that an error occurred in Authlete.
In either case, from the viewpoint of the client application, it is an error on the server side.
Therefore, the service implementation should generate a response to the client application with
HTTP status of "500 Internal Server Error".
The value of `responseContent` is a JSON string which describes the error, so it can be used
as the entity body of the response.
The following illustrates the response which the service implementation should generate and return
to the client application.
```
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}
```
The endpoint implementation may return another different response to the client application
since "500 Internal Server Error" is not required by OAuth 2.0.
**OK**
When the value of `action` is `OK`, it means that Authlete's `/auth/token/issue` API successfully
generated an access token.
The HTTP status of the response returned to the client application must be "200 OK" and the content
type must be`application/json`.
The value of `responseContent` is a JSON string which contains an access token, so it can be used
as the entity body of the response.
The following illustrates the response which the service implementation must generate and return
to the client application.
```
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}
```

## Path parameters

- `serviceId` string, required

## Request body

- TokenIssueRequest
  - `ticket` string, required — The ticket issued from Authlete `/auth/token` API.
  - `subject` string, required — The subject (= unique identifier) of the authenticated user.
  - `properties` Property[] — Extra properties to associate with a newly created access token. Note that properties parameter is accepted only when `Content-Type` of the request is `application/json`, so don't use `application/x-www-form-urlencoded` if you want to specify properties.
    - `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.
  - `jwtAtClaims` string — Additional claims that are added to the payload part of the JWT access token.
  - `accessToken` string — The representation of an access token that may be issued as a result of the Authlete API call.
  - `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.

## Response `200`

Token issued successfully

- TokenIssueResponse
  - `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' | 'OK' — 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 is JSON.
  - `accessToken` string — The newly issued access token. This parameter is a non-null value only when the value of `action` parameter is `OK`.
  - `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 refresh token. This parameter is a non-null value only when `action` is `OK` and the service supports the refresh token flow. If `refreshTokenKept` is set to `false`, a new refresh token is issued and the old refresh token used in the refresh token flow is invalidated. On the contrary, if `refreshTokenKept` is set to `true`, the refresh token itself is not refreshed.
  - `refreshTokenExpiresAt` 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.
  - `clientId` integer — The client ID.
  - `clientIdAlias` string — The client ID alias. If the client did not have an alias, 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 calling `/api/auth/token` API, this parameter is `null` if the flow of the token request was [Client Credentials Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) (`grant_type=client_credentials`) because it means the access token is not associated with any specific end-user.
  - `scopes` 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.
  - `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.
  - `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.
  - `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.
  - `refreshTokenScopes` string[] — The scopes associated with the refresh token. May be null.
  - `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

- **2025-12-18** `504771740022` — 2 info
  - added the optional property `metadataDocumentLocation` to the response with the `200` status
  - added the optional property `metadataDocumentUsed` to the response with the `200` status

[Change history](https://skmtc.dev/authlete/apis/authlete-api/changes/api/:serviceId/auth/token/issue/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)