Customer Authentication

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

Read current authentication options

Read current authentication options.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Current 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.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/authentication-options
Request samples
$authenticationOptions = $client->authenticationOptions()->load();
Response samples
application/json
[
  • {
    }
]

Change authentication options

Change options.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
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
200Authentication 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.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid 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.

Request
Security:
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A 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
token
string

The token identifier string.

otpRequired
boolean

Should OTP be required to exchange this token.

credentialId
string <= 50 characters

The credential's ID.

username
required
string

The token's username.

customerId
string <= 50 characters

The token's customer ID.

expiredTime
string <date-time>

Token's expired time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/authentication-tokens
Request samples
$authenticationTokens = $client->authenticationTokens()->search([
    'filter' => 'customerId:testCustomer',
]);
Response samples
application/json
[
  • {
    }
]

Login

Login a customer.

Request
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

AuthenticationToken resource.

mode
string
Default: "password"

The token's generation mode.

otpRequired
boolean

Should OTP be required to exchange this token.

username
required
string

The token's username.

password
required
string <password>

The token's password.

expiredTime
string <date-time>

Token's expired time.

Responses
201Login successful.
Response Schema: application/json
token
string

The token identifier string.

otpRequired
boolean

Should OTP be required to exchange this token.

credentialId
string <= 50 characters

The credential's ID.

username
required
string

The token's username.

customerId
string <= 50 characters

The token's customer ID.

expiredTime
string <date-time>

Token's expired time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid 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.

Request
path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Authentication Token was verified.
Response Schema: application/json
token
string

The token identifier string.

otpRequired
boolean

Should OTP be required to exchange this token.

credentialId
string <= 50 characters

The credential's ID.

username
required
string

The token's username.

customerId
string <= 50 characters

The token's customer ID.

expiredTime
string <date-time>

Token's expired time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource 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.

Request
path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204Customer was logged out.
401Unauthorized access, invalid credentials was used.
404Resource was not found.
delete/authentication-tokens/{token}
Request samples
$client->authenticationTokens()->logout('token');
Response samples
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Exchange

Exchange Authentication Token for JWT.

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

Request
path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
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)
object
expiredTime
string <date-time>

Session expired time. Defaults to one hour.

Responses
201Authentication Token exchanged for JWT.
Response Schema: application/json
id
string <= 50 characters

The session identifier string.

type
string

Session type.

Value: "customer"
token
string

The session's token used for authentication.

customerId
string <= 50 characters

The customer's ID.

Array of objects (Acl)
object
createdTime
string <date-time>

Session created time.

updatedTime
string <date-time>

Session updated time.

expiredTime
string <date-time>

Session expired time. Defaults to one hour.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource 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.

Request
Security:
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A 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
id
string <= 50 characters

The credential identifier string.

username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

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

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/credentials
Request samples
$customerCredentials = $client->customerCredentials()->search([
    'filter' => 'customerId:testCustomer',
]);
Response samples
application/json
[
  • {
    }
]

Create a credential

Create a credential.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
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
201Credential was created.
Response Schema: application/json
id
string <= 50 characters

The credential identifier string.

username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

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

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid 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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Credential was retrieved successfully.
Response Schema: application/json
id
string <= 50 characters

The credential identifier string.

username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

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

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource 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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
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
200Credential was updated.
Response Schema: application/json
id
string <= 50 characters

The credential identifier string.

username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

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

The links related to resource.

201Credential was created.
Response Schema: application/json
id
string <= 50 characters

The credential identifier string.

username
required
string

Credential's username.

customerId
required
string

The credential's customer ID.

expiredTime
string <date-time>

The credential's expired time.

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

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
422Invalid 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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204Credential was deleted.
401Unauthorized access, invalid credentials was used.
404Resource was not found.
delete/credentials/{id}
Request samples
$client->customerCredentials()->delete('credentialId');
Response samples
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Retrieve a list of tokens

Retrieve a list of tokens.

Request
Security:
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A 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
token
string

The token's identifier string.

username
required
string

The token's username.

credentialId
string

Token's credential ID.

expiredTime
string <date-time>

Password expired time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access 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.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

ResetPasswordToken resource.

username
required
string

The token's username.

expiredTime
string <date-time>

Password expired time.

Responses
201Reset Password Token was created.
Response Schema: application/json
token
string

The token's identifier string.

username
required
string

The token's username.

credentialId
string

Token's credential ID.

expiredTime
string <date-time>

Password expired time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid 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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200ResetPasswordToken was retrieved successfully.
Response Schema: application/json
token
string

The token's identifier string.

username
required
string

The token's username.

credentialId
string

Token's credential ID.

expiredTime
string <date-time>

Password expired time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource 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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204ResetPasswordToken was deleted.
401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
409Conflict.
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": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}