logo

Customer Authentication

Create authentication credentials, login, logout, and verify your customers.

Read current authentication options

Read current authentication options.

SecuritySecretApiKey or JWT
Responses
200

Current authentication options was retrieved successfully.

Response Schema: application/json
Array
passwordPattern
string

Allowed password pattern.

credentialTtl
integer

The default lifetime of the credential in seconds.

authTokenTtl
integer

The default lifetime of the auth-token in seconds.

resetTokenTtl
integer

The default lifetime of the reset-token in seconds.

otpRequired
boolean

Should OTP be required to exchange token.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/authentication-options
Request samples
$authenticationOptions = $client->authenticationOptions()->load();
Response samples
application/json
[
  • {
    }
]

Change authentication options

Change options.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Authentication Options resource.

passwordPattern
string

Allowed password pattern.

credentialTtl
integer

The default lifetime of the credential in seconds.

authTokenTtl
integer

The default lifetime of the auth-token in seconds.

resetTokenTtl
integer

The default lifetime of the reset-token in seconds.

otpRequired
boolean

Should OTP be required to exchange token.

Responses
200

Authentication Options were updated.

Response Schema: application/json
passwordPattern
string

Allowed password pattern.

credentialTtl
integer

The default lifetime of the credential in seconds.

authTokenTtl
integer

The default lifetime of the auth-token in seconds.

resetTokenTtl
integer

The default lifetime of the reset-token in seconds.

otpRequired
boolean

Should OTP be required to exchange token.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

put/authentication-options
Request samples
application/json
{
  • "passwordPattern": "string",
  • "credentialTtl": 0,
  • "authTokenTtl": 0,
  • "resetTokenTtl": 0,
  • "otpRequired": true
}
Response samples
application/json
{
  • "passwordPattern": "string",
  • "credentialTtl": 0,
  • "authTokenTtl": 0,
  • "resetTokenTtl": 0,
  • "otpRequired": true
}

Retrieve a list of auth tokens

Retrieve a list of auth tokens.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

Responses
200

A list of auth tokens was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
username
required
string

The token's username.

token
string

The token identifier string.

otpRequired
boolean

Should OTP be required to exchange this token.

credentialId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

Token's expired time.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/authentication-tokens
Request samples
$authenticationTokens = $client->authenticationTokens()->search([
    'filter' => 'customerId:testCustomer',
]);
Response samples
application/json
[
  • {
    }
]

Login

Login a customer.

SecuritySecretApiKey or JWT or PublishableApiKey
Request
Request Body schema: application/json

AuthenticationToken resource.

username
required
string

The token's username.

password
required
string <password>

The token's password.

mode
string
Default: "password"

The token's generation mode. A SecretApiKey must be used to login in passwordless mode.

otpRequired
boolean

Should OTP be required to exchange this token.

expiredTime
string <date-time>

Token's expired time.

Responses
201

Login successful.

Response Schema: application/json
username
required
string

The token's username.

token
string

The token identifier string.

otpRequired
boolean

Should OTP be required to exchange this token.

credentialId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

Token's expired time.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/authentication-tokens
Request samples
application/json
{
  • "mode": "password",
  • "otpRequired": true,
  • "username": "string",
  • "password": "pa$$word",
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "token": "string",
  • "otpRequired": true,
  • "credentialId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "username": "string",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "mode": "password"
}

Verify

Verify an authentication token.

SecuritySecretApiKey or JWT or PublishableApiKey
Request
path Parameters
token
required
string

The token identifier string.

Responses
200

Authentication Token was verified.

Response Schema: application/json
username
required
string

The token's username.

token
string

The token identifier string.

otpRequired
boolean

Should OTP be required to exchange this token.

credentialId
string <= 50 characters

The resource ID. Defaults to UUID v4.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

Token's expired time.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/authentication-tokens/{token}
Request samples
$isVerified = $client->authenticationTokens()->verify('token');
Response samples
application/json
{
  • "token": "string",
  • "otpRequired": true,
  • "credentialId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "username": "string",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "mode": "password"
}

Logout a customer

Logout a customer.

SecuritySecretApiKey or JWT or PublishableApiKey
Request
path Parameters
token
required
string

The token identifier string.

Responses
204

Customer was logged out.

401

Unauthorized access, invalid credentials were used.

404

Resource was not found.

delete/authentication-tokens/{token}
Request samples
$client->authenticationTokens()->logout('token');
Response samples
application/json
{
  • "status": 401,
  • "type": "http://example.com",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Exchange

Exchange Authentication Token for JWT.

It will also invalidate an Authentication Token by default (so it can only be exchanged once).

SecuritySecretApiKey or JWT or PublishableApiKey
Request
path Parameters
token
required
string

The token identifier string.

Request Body schema: application/json
invalidate
boolean
Default: true

Whether to invalidate token after exchange or not.

oneTimePassword
string^[0-9]{6}$

The one time password sent via an email. Should contain digits only.

Array of objects (Acl)
Array
required
object

Api Key scope.

permissions
required
Array of strings <operationId>

Specify individual permission here if creating a restricted API key. Use wildcard * for full access.

object
property name*
additional property
any
expiredTime
string <date-time>

Session expired time. Defaults to one hour.

Responses
201

Authentication Token exchanged for JWT.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

type
string

Session type.

Value: "customer"
token
string

The session's token used for authentication.

customerId
string <= 50 characters

The resource ID. Defaults to UUID v4.

Array of objects (Acl)
Array
required
object

Api Key scope.

permissions
required
Array of strings <operationId>

Specify individual permission here if creating a restricted API key. Use wildcard * for full access.

object
property name*
additional property
any
createdTime
string <date-time>

Session created time.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

expiredTime
string <date-time>

Session expired time. Defaults to one hour.

Array of objects (CustomerLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Enum: "customer" "targetCustomer"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

post/authentication-tokens/{token}/exchange
Request samples
application/json
{
  • "invalidate": true,
  • "oneTimePassword": "123456",
  • "acl": [
    ],
  • "customClaims": {},
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "type": "customer",
  • "token": "string",
  • "customerId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "acl": [
    ],
  • "customClaims": {},
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a list of credentials

Retrieve a list of credentials.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

Responses
200

A list of Credentials was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

The credential's expired time.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/credentials
Request samples
$customerCredentials = $client->customerCredentials()->search([
    'filter' => 'customerId:testCustomer',
]);
Response samples
application/json
[
  • {
    }
]

Create a credential

Create a credential.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Credential resource.

username
required
string

Credential's username.

password
required
string <password>

The credential's password.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

Responses
201

Credential was created.

Response Schema: application/json
username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

The credential's expired time.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/credentials
Request samples
application/json
{
  • "username": "string",
  • "password": "pa$$word",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "username": "string",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a credential

Retrieve a credential with specified identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

Credential was retrieved successfully.

Response Schema: application/json
username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

The credential's expired time.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/credentials/{id}
Request samples
$customerCredential = $client->customerCredentials()->load('credentialId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "username": "string",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Create or update a credential with predefined ID

Create or update a credential with predefined identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Credential resource.

username
required
string

Credential's username.

password
required
string <password>

The credential's password.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

Responses
200

Credential was updated.

Response Schema: application/json
username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

The credential's expired time.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

201

Credential was created.

Response Schema: application/json
username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

id
string <= 50 characters

The resource ID. Defaults to UUID v4.

expiredTime
string <date-time>

The credential's expired time.

Array of SelfLink (object) or CustomerLink (object) non-empty

The links related to resource.

Array (non-empty)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

put/credentials/{id}
Request samples
application/json
{
  • "username": "string",
  • "password": "pa$$word",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "username": "string",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Delete a credential

Delete a credential with predefined identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
204

Credential was deleted.

401

Unauthorized access, invalid credentials were used.

404

Resource was not found.

delete/credentials/{id}
Request samples
$client->customerCredentials()->delete('credentialId');
Response samples
application/json
{
  • "status": 401,
  • "type": "http://example.com",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Retrieve a list of tokens

Retrieve a list of tokens.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

Responses
200

A list of Reset Password Tokens was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
username
required
string

The token's username.

token
string

The token's identifier string.

credentialId
string

Token's credential ID.

expiredTime
string <date-time>

Password expired time.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/password-tokens
Request samples
// all parameters are optional
const firstCollection = await api.customerAuthentication.getAllResetPasswordTokens();

// alternatively you can specify one or more of them
const params = {limit: 20, offset: 100}; 
const secondCollection = await api.customerAuthentication.getAllResetPasswordTokens(params);

// access the collection items, each item is a Member
secondCollection.items.forEach(token => console.log(token.fields.token));
Response samples
application/json
[
  • {
    }
]

Create a Reset Password Token

Create a Reset Password Token.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

ResetPasswordToken resource.

username
required
string

The token's username.

expiredTime
string <date-time>

Password expired time.

Responses
201

Reset Password Token was created.

Response Schema: application/json
username
required
string

The token's username.

token
string

The token's identifier string.

credentialId
string

Token's credential ID.

expiredTime
string <date-time>

Password expired time.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/password-tokens
Request samples
application/json
{
  • "username": "string",
  • "expiredTime": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "token": "string",
  • "username": "string",
  • "credentialId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a Reset Password Token

Retrieve a Reset Password Token with specified identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

ResetPasswordToken was retrieved successfully.

Response Schema: application/json
username
required
string

The token's username.

token
string

The token's identifier string.

credentialId
string

Token's credential ID.

expiredTime
string <date-time>

Password expired time.

Array of objects (SelfLink) non-empty

The links related to resource.

Array (non-empty)
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/password-tokens/{id}
Request samples
const token = await api.customerAuthentication.getResetPasswordToken({id: 'my-first-id'});
console.log(token.fields.credential);
Response samples
application/json
{
  • "token": "string",
  • "username": "string",
  • "credentialId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Delete a Reset Password Token

Delete a Reset Password Token with predefined identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
204

ResetPasswordToken was deleted.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

409

Conflict.

delete/password-tokens/{id}
Request samples
const request = await api.customerAuthentication.deleteResetPasswordToken({id: 'my-second-key'});

// the request does not return any fields but
// you can confirm the success using the status code
console.log(request.response.status); // 204
Response samples
application/json
{
  • "status": 401,
  • "type": "http://example.com",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}
➔ Next to Tags