Customer Authentication

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

Read current authentication options

Read current authentication options.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Request samples

$authenticationOptions = $client->authenticationOptions()->load();

Response samples

Content type
application/json
[
  • {
    }
]

Change authentication options

Change options.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Request samples

Content type
application/json
{
  • "passwordPattern": "string",
  • "credentialTtl": 0,
  • "authTokenTtl": 0,
  • "resetTokenTtl": 0,
  • "otpRequired": true
}

Response samples

Content type
application/json
{
  • "passwordPattern": "string",
  • "credentialTtl": 0,
  • "authTokenTtl": 0,
  • "resetTokenTtl": 0,
  • "otpRequired": true
}

Retrieve a list of auth tokens

Retrieve a list of auth tokens.

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

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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 (SelfLink) non-empty

The links related to resource.

Request samples

$authenticationTokens = $client->authenticationTokens()->search([
    'filter' => 'customerId:testCustomer',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Login

Login a customer.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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 (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
Example
{
  • "mode": "password",
  • "otpRequired": true,
  • "username": "string",
  • "password": "pa$$word",
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
Example
{
  • "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.

path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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 (SelfLink) non-empty

The links related to resource.

Request samples

$isVerified = $client->authenticationTokens()->verify('token');

Response samples

Content type
application/json
Example
{
  • "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.

path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Request samples

$client->authenticationTokens()->logout('token');

Response samples

Content type
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).

path Parameters
token
required
string

The token identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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

The session identifier string.

type
string
Value: "customer"

Session type.

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 (CustomerLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "invalidate": true,
  • "oneTimePassword": "123456",
  • "acl": [
    ],
  • "customClaims": {},
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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.

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

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Request samples

$customerCredentials = $client->customerCredentials()->search([
    'filter' => 'customerId:testCustomer',
]);

Response samples

Content type
application/json
[
  • {
    }
]

Create a credential

Create a credential.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "pa$$word",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Request samples

$customerCredential = $client->customerCredentials()->load('credentialId');

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

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

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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.

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "pa$$word",
  • "customerId": "string",
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Request samples

$client->customerCredentials()->delete('credentialId');

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}

Retrieve a list of tokens

Retrieve a list of tokens.

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

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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 (SelfLink) non-empty

The links related to resource.

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

Content type
application/json
[
  • {
    }
]

Create a Reset Password Token

Create a Reset Password Token.

Authorizations:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Request Body schema: application/json

ResetPasswordToken resource.

username
required
string

The token's username.

expiredTime
string <date-time>

Password expired time.

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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 (SelfLink) non-empty

The links related to resource.

Request samples

Content type
application/json
{
  • "username": "string",
  • "expiredTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

Response Headers
Rate-Limit-Limit
integer

The number of allowed requests in the current period.

Rate-Limit-Remaining
integer

The number of remaining requests in the current period.

Rate-Limit-Reset
string

The date in format defined by RFC 822 when the current period will reset.

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 (SelfLink) non-empty

The links related to resource.

Request samples

const token = await api.customerAuthentication.getResetPasswordToken({id: 'my-first-id'});
console.log(token.fields.credential);

Response samples

Content type
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.

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

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters
Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

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

Responses

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

Content type
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}