Issue Token Response - Authlete Documentation

Full 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
&#123;responseContent&#125;

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 beapplication/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
&#123;responseContent&#125;

Authorizations

Authorization

string

header

required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> 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.

Path Parameters

serviceId

string

required

A service ID.

Body

ticket

string

required

The ticket issued from Authlete /auth/token API.

subject

string

required

The subject (= unique identifier) of the authenticated user.

properties

object[]

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.

Show child attributes

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<int64>

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<int64>

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

Token issued successfully

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

enum<string>

The next action that the authorization server implementation should take.

Available options:

INTERNAL_SERVER_ERROR,

OK

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<int64>

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<int64>

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<int64>

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<int64>

The duration of the newly issued refresh token in seconds.

clientId

integer<int64>

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 (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

object[]

The extra properties associated with the access token. This parameter is null when no extra property is associated with the issued access token.

Show child attributes

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

object

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".

Show child attributes

serviceAttributes

object[]

The attributes of this service that the client application belongs to.

Show child attributes

clientAttributes

object[]

The attributes of the client.

Show child attributes

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 (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.

Authlete

​INTERNAL_SERVER_ERROR

​OK

Authorizations

Path Parameters

Body

Response

INTERNAL_SERVER_ERROR

OK