Documentation

TokenCreateRequest implements ArrayCopyable, Arrayable, Jsonable Uses ArrayTrait, JsonTrait

Request to Authlete's /api/auth/token/create API.

The API can be used to create an arbitrary access token without using standard flows.

Interfaces, Classes and Traits

ArrayCopyable
Interface to declare instances can be converted into/from arrays.
Arrayable
Interface to declare that instances can be converted into an array.
Jsonable
Interface to declare that instances can be converted into JSON strings.

Table of Contents

copyFromArray()  : mixed
Copy the content of the given array into this object.
copyToArray()  : mixed
Copy the content of this object into the given array.
fromArray()  : static
Convert an array into an instance of this class.
fromJson()  : static
Convert a JSON string into an instance of this class.
getAccessToken()  : string
Get the value of the new access token.
getAccessTokenDuration()  : int|string
Get the duration of a newly created access token in seconds.
getCertificateThumbprint()  : string
Get the thumbprint of the client certificate bound to the access token.
getClientId()  : int|string
Get the ID of the client application which will be associated with a newly created access token.
getDpopKeyThumbprint()  : string
Get the thumbprint of the public key used for DPoP presentation of this access token. If this request parameter is set, a DPoP proof signed with the corresponding private key must be presented when the client uses the access token.
getGrantType()  : GrantType
Get the grant type to be emulated for a newly created access token.
getProperties()  : array<string|int, Property>
Get properties to be associated with a newly created access token.
getRefreshToken()  : string
Get the value of the new refresh token.
getRefreshTokenDuration()  : int|string
Get the duration of a newly created refresh token in seconds.
getScopes()  : array<string|int, string>
Get the scopes which will be associated with a newly created access token.
getSubject()  : string
Get the subject (= unique identifier) of the end-user who will be associated with a newly created access token.
isAccessTokenPersistent()  : bool
Get whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service.
isClientIdAliasUsed()  : bool
Get the flag 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.
setAccessToken()  : TokenCreateRequest
Set the value of the new access token.
setAccessTokenDuration()  : TokenCreateRequest
Set the duration of a newly created access token in seconds.
setAccessTokenPersistent()  : TokenCreateRequest
Set whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service.
setCertificateThumbprint()  : TokenCreateRequest
Set the thumbprint of the client certificate bound to the access token.
setClientId()  : TokenCreateRequest
Set the ID of the client application which will be associated with a newly created access token.
setClientIdAliasUsed()  : TokenCreateRequest
Set the flag 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.
setDpopKeyThumbprint()  : TokenCreateRequest
Set the thumbprint of the public key used for DPoP presentation of this access token. If this request parameter is set, a DPoP proof signed with the corresponding private key must be presented when the client uses the access token.
setGrantType()  : TokenCreateRequest
Set the grant type to be emulated for a newly created access token.
setProperties()  : TokenCreateRequest
Set properties to be associated with a newly created access token.
setRefreshToken()  : TokenCreateRequest
Set the value of the new refresh token.
setRefreshTokenDuration()  : TokenCreateRequest
Set the duration of a newly created refresh token in seconds.
setScopes()  : TokenCreateRequest
Set the scopes which will be associated with a newly created access token.
setSubject()  : TokenCreateRequest
Set the subject (= unique identifier) of the end-user who will be associated with a newly created access token.
toArray()  : array<string|int, mixed>
Convert this object into an array.
toJson()  : string
Convert this object into a JSON string.

Methods

copyFromArray()

Copy the content of the given array into this object.

public copyFromArray(array<string|int, mixed> &$array) : mixed
Parameters
$array : array<string|int, mixed>
Return values
mixed —

copyToArray()

Copy the content of this object into the given array.

public copyToArray(array<string|int, mixed> &$array) : mixed
Parameters
$array : array<string|int, mixed>
Return values
mixed —

fromArray()

Convert an array into an instance of this class.

public static fromArray([array<string|int, mixed> $array = null ]) : static

This static function returns a new instance of this class. If $array is null, null is returned.

Parameters
$array : array<string|int, mixed> = null

An array

Return values
static —

An instance of this class.

fromJson()

Convert a JSON string into an instance of this class.

public static fromJson(string $json) : static

This static function returns a new instance of this class. If $json is null or the type of $json is not string, null is returned.

Parameters
$json : string

A JSON string.

Return values
static —

An instance of this class.

getAccessToken()

Get the value of the new access token.

public getAccessToken() : string
Return values
string —

The value of the new access token.

getAccessTokenDuration()

Get the duration of a newly created access token in seconds.

public getAccessTokenDuration() : int|string
Return values
int|string —

The duration of the access token.

getCertificateThumbprint()

Get the thumbprint of the client certificate bound to the access token.

public getCertificateThumbprint() : string

If this request parameter is set, a certificate whose thumbprint matches the value must be presented when the client uses the access token.

Tags
see
https://www.rfc-editor.org/rfc/rfc8705.html

RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens

since
1.8
Return values
string —

The base64url-encoded SHA-256 certificate thumbprint.

getClientId()

Get the ID of the client application which will be associated with a newly created access token.

public getClientId() : int|string
Return values
int|string —

The client ID.

getDpopKeyThumbprint()

Get the thumbprint of the public key used for DPoP presentation of this access token. If this request parameter is set, a DPoP proof signed with the corresponding private key must be presented when the client uses the access token.

public getDpopKeyThumbprint() : string

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Tags
since
1.8
Return values
string —

The JWK publick key thumbprint.

getProperties()

Get properties to be associated with a newly created access token.

public getProperties() : array<string|int, Property>
Return values
array<string|int, Property> —

Properties.

getRefreshToken()

Get the value of the new refresh token.

public getRefreshToken() : string
Return values
string —

The value of the new refresh token.

getRefreshTokenDuration()

Get the duration of a newly created refresh token in seconds.

public getRefreshTokenDuration() : int|string
Return values
int|string —

The duration of the refresh token.

getScopes()

Get the scopes which will be associated with a newly created access token.

public getScopes() : array<string|int, string>
Return values
array<string|int, string> —

The scopes.

getSubject()

Get the subject (= unique identifier) of the end-user who will be associated with a newly created access token.

public getSubject() : string
Return values
string —

The subject of the end-user.

isAccessTokenPersistent()

Get whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service.

public isAccessTokenPersistent() : bool

If this request parameter is true then the access token will not automatically expire.

If this request parameter is true, the accessTokenDuration request parameter is ignored.

Tags
since
1.8
Return values
bool —

false if the access token expires (default). true if the access token does not expire.

isClientIdAliasUsed()

Get the flag 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.

public isClientIdAliasUsed() : bool
Return values
bool —

true if use of the client ID alias is emulated.

setAccessToken()

Set the value of the new access token.

public setAccessToken(string $accessToken) : TokenCreateRequest

This request parameter is optional.

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 the accessToken request parameter. The implementation of the /api/auth/token/create API 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.

Parameters
$accessToken : string

The value of the new access token.

Return values
TokenCreateRequest —

$this object.

setAccessTokenDuration()

Set the duration of a newly created access token in seconds.

public setAccessTokenDuration(int|string $duration) : TokenCreateRequest

If $duration is 0, the duration is determined according to the settings of the service. This request parameter is optional.

Parameters
$duration : int|string

The duration of the access token.

Return values
TokenCreateRequest —

$this object.

setAccessTokenPersistent()

Set whether the access token expires or not. By default, all access tokens expire after a period of time determined by their service.

public setAccessTokenPersistent(bool $persistent) : TokenCreateRequest

If this request parameter is true then the access token will not automatically expire.

If this request parameter is true, the accessTokenDuration request parameter is ignored.

Parameters
$persistent : bool

false to make the access token expire (default). true to make the access token be persistent.

Tags
since
1.8
Return values
TokenCreateRequest —

$this object.

setCertificateThumbprint()

Set the thumbprint of the client certificate bound to the access token.

public setCertificateThumbprint(string $thumbprint) : TokenCreateRequest

If this request parameter is set, a certificate whose thumbprint matches the value must be presented when the client uses the access token.

Parameters
$thumbprint : string

The base64url-encoded SHA-256 certificate thumbprint.

Tags
see
https://www.rfc-editor.org/rfc/rfc8705.html

RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens

since
1.8
Return values
TokenCreateRequest —

$this object.

setClientId()

Set the ID of the client application which will be associated with a newly created access token.

public setClientId(int|string $clientId) : TokenCreateRequest

This request parameter is mandatory.

Parameters
$clientId : int|string

The client ID.

Return values
TokenCreateRequest —

$this object.

setClientIdAliasUsed()

Set the flag 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.

public setClientIdAliasUsed(bool $used) : TokenCreateRequest

This has an effect only on the value of the aud claim in a response from a userinfo endpoint. 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 request parameter 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 request parameter has no effect (it is always regarded as false).

Parameters
$used : bool

true to emulate use of the client ID alias.

Return values
TokenCreateRequest —

$this object.

setDpopKeyThumbprint()

Set the thumbprint of the public key used for DPoP presentation of this access token. If this request parameter is set, a DPoP proof signed with the corresponding private key must be presented when the client uses the access token.

public setDpopKeyThumbprint(string $thumbprint) : TokenCreateRequest

See "OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)" for details.

Parameters
$thumbprint : string

The JWK publick key thumbprint.

Tags
since
1.8
Return values
TokenCreateRequest —

$this object.

setGrantType()

Set the grant type to be emulated for a newly created access token.

public setGrantType([GrantType $grantType = null ]) : TokenCreateRequest

When $grantType is either GrantType::$IMPLICIT or GrantType::$CLIENT_CREDENTIALS, a refresh token is not issued. This request parameter is mandatory.

Parameters
$grantType : GrantType = null

The grant type.

Return values
TokenCreateRequest —

$this object.

setProperties()

Set properties to be associated with a newly created access token.

public setProperties([array<string|int, Property> $properties = null ]) : TokenCreateRequest

Note that the properties request 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 use this properties request parameter.

Parameters
$properties : array<string|int, Property> = null

Properties.

Return values
TokenCreateRequest —

$this object.

setRefreshToken()

Set the value of the new refresh token.

public setRefreshToken(string $refreshToken) : TokenCreateRequest

This request parameter is optional.

The /api/auth/token/create API generates a refresh token as necessary. 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 the refreshTokenrequest parameter. The implementation of the /api/auth/token/create API 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.

Parameters
$refreshToken : string

The value of the new refresh token.

Return values
TokenCreateRequest —

$this object.

setRefreshTokenDuration()

Set the duration of a newly created refresh token in seconds.

public setRefreshTokenDuration(int|string $duration) : TokenCreateRequest

If $duration is 0, the duration is determined according to the settings of the service. This request parameter is optional.

No refresh token is created (1) if the service is configured not to support GrantType::$REFRESH_TOKEN, or (2) if the specified grant type is either GrantType::$IMPLICIT or GrantType::$CLIENT_CREDENTIALS.

Parameters
$duration : int|string

The duration of the refresh token.

Return values
TokenCreateRequest —

$this object.

setScopes()

Set the scopes which will be associated with a newly created access token.

public setScopes([array<string|int, string> $scopes = null ]) : TokenCreateRequest

Scopes that are not supported by the service cannot be specified and requesting them will cause an error. This request parameter is optional.

Parameters
$scopes : array<string|int, string> = null

The scopes.

Return values
TokenCreateRequest —

$this object.

setSubject()

Set the subject (= unique identifier) of the end-user who will be associated with a newly created access token.

public setSubject(string $subject) : TokenCreateRequest

This request parameter is required unless the grant type is GrantType::$CLIENT_CREDENTIALS. The value must consist of only ASCII characters and its length must not exceed 100.

Parameters
$subject : string

The subject of the end-user.

Return values
TokenCreateRequest —

$this object.

toArray()

Convert this object into an array.

public toArray() : array<string|int, mixed>
Return values
array<string|int, mixed> —

An array.

toJson()

Convert this object into a JSON string.

public toJson(int $options) : string
Parameters
$options : int

Options passed to json_encode(). This parameter is optional and its default value is 0.

Return values
string —

A JSON string.

Search results