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.

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"
}

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.

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"
}

Renew Token

PUT

/v1/token

(identity)

Renew token before it expires.

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"
}

Navigation

Identity Token Authentication API

Acquire Token

Scope Token Context

Renew Token