Identity Token Authentication API

Reference material for usage on API Guidelines > Authentication.

Acquire Token

Almost all requests require a X-Auth-Token header to any service endpoint.

POST

/v1/token

(identity)

Authenticate and obtain valid token (V1).

Service
identity

Tokens expire after 1 hour by default and can be renewed by doing PUT action on /v1/token, to get another extended token. Tokens are scoped to specific levels of access and restricted to only access the domain and tenant they are scoped for.

During authentication token is scoped by default to no tenant and domain unless specified. There is one exception if the user has no global roles and customer role he will be scoped to one tenant by default.

You can provide the "domain" parameter in the request to scope the token to that specific domain on authentication. The "user_domain" parameter is used to identify in which domain the user is located for authentication purposes. If no "user_domain" parameter is provided, the "domain" parameter will be assumed for the user domain. If no "domain" parameter is provided but a “user_domain” parameter is provided the token will be un-scoped.

Request Parameters

Name	In	Type	Description	MUST include
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
domain	body	string	Optional Domain to set token context.
password	body	string	User Account Password.	X
tenant_id	body	string	Optional Tenant-ID to set token context.
user_domain	body	string	Parent Domain for user account.	X
username	body	string	Username.	X

Request Example

{
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "credentials": {
        "password": "secret"
    }
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
domain	body	string	currently scoped domain for token.
exp	body	integer	token expiration time in seconds since unix epoch.
name	body	string	user name field value.
roles	body	string	list of assigned user roles to token.
token	body	string	token to be used for further requests.
user_domain	body	string	domain in which user resides.
user_id	body	string	internal UUID of user account.
username	body	string	login username.

Response Example

{
    "user_id": "c31a8f26-26e2-11ee-8506-af6e8a7f3a67",
    "metadata": {
        "name": "Test User Name",
        "system": false
    },
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example",
    "exp": 1689849985,
    "roles": [
        "Root"
    ],
    "token": "TOKEN_FOR_X-AUTH-TOKEN_HEADER"
}

POST

/v2/token

(identity)

Authenticate and obtain valid token (V2).

Service
identity

Authentication tokens expire after 1 hour, and can be renewed by performing an HTTP PUT request to /v2/token using either the refresh_token obtained when authenticating, or the authenticating users password.

Authentication tokens are scoped to specific levels of access and restricted to only access the domain and tenant they are scoped to.

During authentication, the returned authentication token will be scoped to the provided domain and tenant_id. If no domain is provided, the authentication token will be scoped to the provided user_domain. If no user_domain is provided, the returned authentication token will be scoped to the provided domain. Either the domain or user_domain MUST be provided when authenticating. If no tenant_id is provided, the returned authentication token will not be scoped to a tenant.

When authenticating using the token type set to "minimal", an OTP will not be required if MFA is enabled for the user in question. Additionally, when using the "minimal" token type the authenticating user will not be assigned any roles whatsoever. The "minimal" token type is intended for accessing API resources that are not role-specific.

If an authenticating user has no roles assigned under the domain in which they exist, the user will be scoped to one tenant by default when requesting a standard authentication token. This does not apply when requesting a minimal authentication token.

Request Parameters

Name	In	Type	Description	MUST include
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credentials	body	object	Credentials.	X
credentials.otp	body	string	required only if MFA is enabled on the authenticating user and the "type" is set to "standard".
credentials.password	body	string	Credentials Password.	X
domain	body	string	optional Domain to scope authentication token domain context.
method	body	string	the authentication method, must be set to the value "password" for obtaining a new token, regardless of type.	X
tenant_id	body	string	valid tenant_id to scope authentication token tenant context.
type	body	string	the type of the returned authentication token, either "standard" or "minimal".
user_domain	body	string	parent Domain for user account.	X
username	body	string	Username.	X

Request Example

{
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "type": "minimal",
    "method": "password",
    "credentials": {
        "password": "secret"
    }
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
domain	body	string	currently scoped domain for the authentication token.
exp	body	integer	the authentication token expiration time in seconds since unix epoch.
metadata	body	object	Metadata.
metadata.name	body	string	the authenticating user's "name" field value.
refresh_token	body	string	the refresh token used to refresh an expired authentication token or rescope an existing authentication token.
region	body	string	Region.
roles	body	array	a list of user roles assigned to the returned authentication token.
token	body	string	the authentication token to be used for further requests.
user_defined_timezone	body	string	the timezone configured for the authenticating user.
user_domain	body	string	domain in which user resides.
user_id	body	string	internal UUID of user account.
user_region	body	string	User Region.
username	body	string	login username.

Response Example

{
    "user_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "user_region": "Region1",
    "region": null,
    "exp": "1743068021",
    "token": "XXX",
    "refresh_token": "XXX",
    "metadata": {
        "name": "Test Example"
    },
}

Scope Token Context

It is necessary to update a token to change context, when working with an unscoped token.

PATCH

/v1/token

(identity)

Scope token to specific domain (V1).

Service
identity

You can scope token to a specific domain and tenant or only to a specific domain. The tenant_id parameter can be left out or set to null.

The context and authorisation roles are stored inside the token. You, however, can not scope a scoped token from one context to another context.

It would be a good idea to keep the relevant un-scoped token and use that to switch and generate new tokens using the below API call.

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
domain	body	string	valid domain to scope token domain context.
tenant_id	body	string	valid tenant_id to scope token tenant context.

Request Example

{
    "domain": "{domain}",
    "tenant_id": "{tenant_id}"
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
domain	body	string	currently scoped domain for token.
exp	body	integer	token expiration time in seconds since unix epoch.
name	body	string	user name field value.
roles	body	string	list of assigned user roles to token.
token	body	string	token to be used for further requests.
user_domain	body	string	domain in which user resides.
user_id	body	string	internal UUID of user account.
username	body	string	login username.

Response Example

{
    "user_id": "c31a8f26-26e2-11ee-8506-af6e8a7f3a67",
    "metadata": {
        "name": "Test User Name",
        "system": false
    },
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example",
    "exp": 1689849985,
    "roles": [
        "Root"
    ],
    "token": "TOKEN_FOR_X-AUTH-TOKEN_HEADER"
}

PATCH

/v2/token

(identity)

Scope token to specific domain (V2).

Service
identity

An existing authentication token can be scoped to a specific domain and tenant, or only a domain. The context and authorisation roles are stored within the token.

When scoping a "minimal" authentication token, the returned token will also be a "minimal" authentication token. When scoping a "standard" authentication token, the returned token will also be a "standard" authentication token.

Request Parameters

Name	In	Type	Description	MUST include
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credentials	body	object	Credentials.	X
credentials.password	body	string	required if only if "method" is set to "password".
credentials.token	body	string	the refresh_token obtained when originally authenticating. Required only if "method" is set to "refresh_token"
domain	body	string	valid domain to scope authentication token domain context.
method	body	string	the authentication method, can be set to either "password" or "refresh_token"	X
tenant_id	body	string	valid tenant_id to scope authentication token tenant context.
user_domain	body	string	parent domain for the authenticating user account.	X
username	body	string	Username.	X

Request Example

{
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "method": "refresh_token",
    "credentials": {
        "token": "XXX"
    }
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
domain	body	string	currently scoped domain for authentication token.
exp	body	integer	the authentication token expiration time in seconds since unix epoch.
metadata	body	object	Metadata.
metadata.name	body	string	the authenticating user's "name" field value.
refresh_token	body	string	the refresh token used to refresh an expired authentication token or rescope an existing authentication token.
region	body	string	Region.
roles	body	array	a list of user roles assigned to the returned authentication token.
token	body	string	the authentication token to be used for further requests.
user_defined_timezone	body	string	the timezone configured for the authenticating user.
user_domain	body	string	domain in which the authenticating user resides.
user_id	body	string	internal UUID of the authenticating user account.
user_region	body	string	User Region.
username	body	string	login username.

Response Example

{
    "user_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "user_region": "Region1",
    "region": null,
    "exp": "1743068021",
    "token": "XXX",
    "refresh_token": "XXX",
    "metadata": {
        "name": "Test Example"
    },
}

Renew Token

PUT

/v1/token

(identity)

Renew token before it expires (V1).

Service
identity

Before a token expires, you can make the below request to receive a new token that will expire in 1 hour.

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
domain	body	string	currently scoped domain for token.
exp	body	integer	token expiration time in seconds since unix epoch.
name	body	string	user name field value.
roles	body	string	list of assigned user roles to token.
token	body	string	token to be used for further requests.
user_domain	body	string	domain in which user resides.
user_id	body	string	internal UUID of user account.
username	body	string	login username.

Response Example

{
    "user_id": "c31a8f26-26e2-11ee-8506-af6e8a7f3a67",
    "metadata": {
        "name": "Test User Name",
        "system": false
    },
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example",
    "exp": 1689849985,
    "roles": [
        "Root"
    ],
    "token": "TOKEN_FOR_X-AUTH-TOKEN_HEADER"
}

PUT

/v2/token

(identity)

Renew token (V2).

Service
identity

After an authentication token has expired, a request can be made to retrieve a renewed authentication token. This can be done by either using the "refresh_token" provided when originally authenticating, or providing the user in question's password.

The renewed authentication token will expire in 1 hour.

Request Parameters

Name	In	Type	Description	MUST include
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
credentials	body	object	Credentials.	X
credentials.password	body	string	required only if "method" is set to "password".
credentials.token	body	string	the refresh_token obtained when originally authenticating, required only if "method" is set to "refresh_token".
domain	body	string	valid domain to scope authentication token domain context.
method	body	string	the authentication method, can be set to either "password" or "refresh_token".	X
tenant_id	body	string	valid tenant_id to scope authentication token tenant context.
user_domain	body	string	parent Domain for the authenticating user account.	X
username	body	string	Username.	X

Request Example

{
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "method": "refresh_token",
    "credentials": {
        "token": "XXX"
    }
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
domain	body	string	currently scoped domain for authentication token.
exp	body	integer	authentication token expiration time in seconds since unix epoch.
metadata	body	object	Metadata.
metadata.name	body	string	user name field value.
refresh_token	body	string	refresh token used to refresh an expired token or rescope an existing token.
region	body	string	Region.
roles	body	array	a list of user roles assigned to the returned authentication token.
token	body	string	authentication token to be used for further requests.
user_defined_timezone	body	string	the timezone configured for the authenticating user.
user_domain	body	string	domain in which authenticating user resides.
user_id	body	string	internal UUID of authenticating user account.
user_region	body	string	User Region.
username	body	string	login username.

Response Example

{
    "user_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "username": "test@example.com",
    "user_domain": "example.com",
    "domain": "example.com",
    "user_region": "Region1",
    "region": null,
    "exp": "1743068021",
    "token": "XXX",
    "refresh_token": "XXX",
    "metadata": {
        "name": "Test Example"
    },
}