---
title: "Create Access Token"
method: POST
path: "/api/{serviceId}/auth/token/create"
tags: ["Token Operations"]
---

# Create Access Token

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

Create an access token.

## Path parameters

- `serviceId` string, required

## Request body

- TokenCreateRequest
  - `grantType` 'AUTHORIZATION_CODE' | 'IMPLICIT' | 'PASSWORD' | 'CLIENT_CREDENTIALS' | 'REFRESH_TOKEN' | 'CIBA' | 'DEVICE_CODE' | 'TOKEN_EXCHANGE' | 'JWT_BEARER' | 'PRE_AUTHORIZED_CODE', required — The grant type of the access token when the access token was created.
  - `clientId` integer, required — The ID of the client application which will be associated with a newly created access token.
  - `subject` string — The subject (= unique identifier) of the user who will be associated with a newly created access token. This parameter is required unless the grant type is `CLIENT_CREDENTIALS`. The value must consist of only ASCII characters and its length must not exceed 100.
  - `scopes` string[] — The scopes which will be associated with a newly created access token. Scopes that are not supported by the service cannot be specified and requesting them will cause an error.
  - `accessTokenDuration` integer — The duration of a newly created access token in seconds. If the value is 0, the duration is determined according to the settings of the service.
  - `refreshTokenDuration` integer — The duration of a newly created refresh token in seconds. If the value is 0, the duration is determined according to the settings of the service. A refresh token is not created (1) if the service does not support `REFRESH_TOKEN`, or (2) if the specified grant type is either `IMPLICIT`or `CLIENT_CREDENTIALS`.
  - `properties` Property[] — Extra properties to associate with a newly created access token. Note that properties parameter is accepted only when the HTTP method of the request is POST and Content-Type of the request is `application/json`, so don't use `GET` method or `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.
  - `clientIdAliasUsed` boolean — A boolean request parameter which indicates whether to emulate that the client ID alias is used instead of the original numeric client ID when a new access token is created. This has an effect only on the value of the aud claim in a response from [UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). When you access the UserInfo endpoint (which is expected to be implemented using Authlete's `/api/auth/userinfo` API and `/api/auth/userinfo/issue` API) with an access token which has been created using Authlete's `/api/auth/token/create` API with this property (`clientIdAliasUsed`) `true`, the client ID alias is used as the value of the aud claim in a response from the UserInfo endpoint. Note that if a client ID alias is not assigned to the client when Authlete's `/api/auth/token/create` API is called, this property (`clientIdAliasUsed`) has no effect (it is always regarded as `false`).
  - `accessToken` string — The value of the new access token. The `/api/auth/token/create` API generates an access token. Therefore, callers of the API do not have to specify values of newly created access tokens. However, in some cases, for example, if you want to migrate existing access tokens from an old system to Authlete, you may want to specify values of access tokens. In such a case, you can specify the value of a newly created access token by passing a non-null value as the value of accessToken request parameter. The implementation of the `/api/auth/token/create` uses the value of the accessToken request parameter instead of generating a new value when the request parameter holds a non-null value. Note that if the hash value of the specified access token already exists in Authlete's database, the access token cannot be inserted and the `/api/auth/token/create` API will report an error.
  - `refreshToken` string — The value of the new refresh token. The `/api/auth/token/create` API may generate a refresh token. Therefore, callers of the API do not have to specify values of newly created refresh tokens. However, in some cases, for example, if you want to migrate existing refresh tokens from an old system to Authlete, you may want to specify values of refresh tokens. In such a case, you can specify the value of a newly created refresh token by passing a non-null value as the value of refreshToken request parameter. The implementation of the `/api/auth/token/create` uses the value of the refreshToken request parameter instead of generating a new value when the request parameter holds a non-null value. Note that if the hash value of the specified refresh token already exists in Authlete's database, the refresh token cannot be inserted and the `/api/auth/token/create` API will report an error.
  - `accessTokenPersistent` boolean — Get whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service. If this request parameter is `true`, then the access token will not automatically expire and must be revoked or deleted manually at the service. If this request parameter is true, the `accessTokenDuration` request parameter is ignored.
  - `certificateThumbprint` string — The thumbprint of the MTLS certificate bound to this token. If this property is set, a certificate with the corresponding value MUST be presented with the access token when it is used by a client. The value of this property must be a SHA256 certificate thumbprint, base64url encoded.
  - `dpopKeyThumbprint` string — The thumbprint of the public key used for DPoP presentation of this token. If this property is set, a DPoP proof signed with the corresponding private key MUST be presented with the access token when it is used by a client. Additionally, the token's `token_type` will be set to 'DPoP'.
  - `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.
  - `resources` string[] — The value of the resources to associate with the token. This property represents the value of one or more `resource` request parameters which is defined in "RFC8707 Resource Indicators for OAuth 2.0".
  - `forExternalAttachment` boolean — the flag which indicates whether the access token is for an external attachment.
  - `jwtAtClaims` string — Additional claims that are added to the payload part of the JWT access token.
  - `acr` string — The Authentication Context Class Reference of the user authentication that the authorization server performed during the course of issuing the access token.
  - `authTime` integer — The time when the user authentication was performed during the course of issuing the access token.
  - `clientEntityIdUsed` boolean — Flag which indicates whether the entity ID of the client was used when the request for the access token was made.
  - `clientIdentifier` string — The client Identifier associated with the newly issued access token.
  - `sessionId` string — The session ID, which is the ID of the user's authentication session, associated with a newly created access token.
  - `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 [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism rather than from the Authlete database.

## Response `200`

Token created successfully

- TokenCreateResponse
  - `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' | 'BAD_REQUEST' | 'FORBIDDEN' | 'OK' — The next action that the authorization server implementation should take.
  - `accessToken` string — The newly issued access token.
  - `clientId` integer — The ID of the client application associated with the access token.
  - `expiresAt` integer — The time at which the access token expires.
  - `expiresIn` integer — The duration of the newly issued access token in seconds.
  - `grantType` string — The grant type for the newly issued access token.
  - `properties` Property[] — The extra properties associated with the 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.
  - `refreshToken` string — The newly issued refresh token.
  - `scopes` string[] — Scopes which are associated with the access token.
  - `subject` string — The subject (= unique identifier) of the user associated with the newly issued access token.
  - `tokenType` string — The token type of the access token.
  - `jwtAccessToken` string — If the authorization server is configured to issue JWT-based access tokens (= if `Service.accessTokenSignAlg` is set to a `non-null` value), a JWT-based access token is issued along with the original random-string one.
  - `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.
  - `forExternalAttachment` boolean — the flag which indicates whether the access token is for an external attachment.
  - `tokenId` string — Set the unique token identifier.
  - `refreshTokenScopes` string[] — The scopes associated with the refresh token. May be null.
  - `clientIdentifier` string — The client Identifier that will be associated with a newly created access token.
  - `sessionId` string — The session ID associated with a newly created access token. NOTE: A refresh token must be associated with a session ID, which is the ID of the user's authentication session, in order to be used to obtain a [Native SSO](https://openid.net/specs/openid-connect-native-sso-1_0.html)-compliant ID token in the refresh token flow.

## Other responses

- `400`
- `401`
- `403`
- `500`

## Changes

- **2025-12-18** `504771740022` — 2 info
  - added the new optional request property `metadataDocumentUsed` (media type: application/json)
  - added the new optional request property `metadataDocumentUsed` (media type: application/x-www-form-urlencoded)

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