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

/v3/token

(identity)

Authenticate and obtain valid token (V3).

Service
identity

Authentication tokens expire after 12 months of not being used actively.

Request Parameters

Name	In	Type	Description	MUST include
X-Domain	header	None	domain context to which obtained token's context must be scoped.
X-Tenant-ID	header	None	ID of the tenant to which the obtained token's context must be scoped.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
domain	body	string	parent domain for user account.	X
otp	body	string	required only if MFA is enabled on the authenticating user.
password	body	string	Password.	X
username	body	string	Username.	X

Request Example

{
    "domain": "example.com",
    "username": "test@example.com",
    "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
context.domain	body	string	the domain to which the authenticated user is currently scoped.
context.tenant_id	body	string	the tenant to which the authenticated user is currently scoped.
creation_time	body	string	Creation Time.
domain	body	string	currently scoped domain for the authentication token.
name	body	string	the authenticating user's "name" field value.
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.
token_app	body	string	The method used to retrieve this token ("api" or "web")
token_id	body	string	the ID identifying the generated token.
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	The region in which the user resides.
user_stack	body	string	The stack against which the user has authenticated.
username	body	string	login username.
version	body	string	Version.

Response Example

{
    "version": 3,
    "user_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWVkaW5nIXoxNzU0MzE1OTA0LCJ2ZXJzaW9uIjozLCJ1c2VyX2lkIjoiMmZmMjE0YjYtMDg0Ny0xMWVmLTk2NDEtMzM0MDRkOWQ3MzY0IiwidXNlcl9kb21haW4iOiJpbnRlcnN0ZWxsaW8uaW8iLCJ0b2tlbl9pZCI6IjE2OWRmOWUwLTcxM2ItMTFmMC1iNTU5LTc5ZjEyMTA1OWEzMSIsImFwcCI6ImFwaSIsImNyZWF0aW9uX3RpbWUiOiIyMDI1LTA4LTA0VDEzOjU4OjI0LjQ5NFoiLCJ1c2VyX3N0YWNrIjoiemEtZ3AteG5sLTEiLCJ1c2VyX3JlZ2lvbiI6IlNvdXRoIEFmcmljYSIsInVzZXJfYWdlbnQiOiJSYXBpZEFQSS80LjMuNSAoTWFjaW50b3NoOyBPUyBYLzE1LjEuMSkgR0NESFRUUFJlcXVlc3QiLCJzb3VyY2VfaXAiOiIxMDIuMjIuMjQ3LjU3IiwibG9jYXRpb24iOiJBbGJlcnRvbiwgR2F1dGVuZywgU291dGggQWZyaWNhIiwibmFtZSI6ImFsZXhAaW50ZXJzdGVsbGlvLmlvIn0.SJJnj0aOY6abVhrinwwM6T-C54usF0lNmQUIGz8agTNCO6mhjsLDepJKap8ha6yjop2OgeJ0yDvarAo-7yC5rb7Ohbm8qluT2CEDeaMSQc6s_-W0gUybt2cgBZhNcV9L-3f9cn-eRfU3Qly131JkFfhuHLGIQTRAXmnV5LLNY9ok6Lg0444o6k7-wekk3bF21TvPcJLmi1vdP4G_7W-0LbySg-rRZwg6rAJdYghMO0MJ5UdbHyk_U2RcT00-xnQyNPvKTosa1V12Wbvr0iwzItipMEIZLInYrDckG6wIdKSeRVn1IGdaA_0XESCrzXaHieWLYbnTqnwnVZGEVkvXMAdzTUHRoRXdJTINApCd_zBiqlIZXtjMDrNut_6GpQBv5QWP9fpxT-iNyAD_9Z-7N47qMhH314y2Q4EjvqNrjYpdiuyRcu6LlQj04RPc6Y2ZqpFA0VlNk_h4b-0cH_tn77QdBBGaE4rRlr7LECSMPzYuTslZX2O44hnwUZt5Vf3pOjy9-F_nb4Uq9KU9t6ZYJZIIADw_sHL8eBylIUc7y_2ZI62a7sF9dV5qRFzGhH4jMP4pA9aRMrQxplrNoVwYhMzSerds7fD62JZjFnseqdfkJyETb916LxRcJwrccHM3GmjBfqqFR997XPLhduZEaYlK-mP54sVMvGFg2Ku7-FM",
    "token_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "token_app": "api",
    "creation_time": "2025-08-04T13:58:24.494Z",
    "user_region": "South Africa",
    "user_stack": "za-gp-xnl-1",
    "user_domain": "example.com",
    "username": "test@example.com",
    "name": "Test User",
    "user_defined_timezone": "Africa/Johannesburg",
    "roles": [
        "Subscriber Administrator",
        "Identity Administrator"
    ],
    "context": {
        "domain": "example.com",
        "tenant_id": null
    }
}

Purge API Key / Token

DELETE

/v3/token

(identity)

Purge Existing Token (V3).

Service
identity

Purges the token supplied in the X-Auth-Token header. The purged token will no longer be valid & cannot be used to make authenticated requests.

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X

Response Status Codes

Code	Meaning
204	OK - No Content
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

Get API Key / Token

GET

/v3/token

(identity)

Get Current Token (V3).

Service
identity

Returns information about the token supplied in the X-Auth-Token header.

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
context.domain	body	string	the domain to which the the current token's context is currently scoped.
context.tenant_id	body	string	the tenant to which the current token's context is currently scoped.
creation_time	body	string	Creation Time.
domain	body	string	currently scoped domain for the authentication token.
name	body	string	the authenticating user's "name" field value.
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.
token_app	body	string	The method used to retrieve this token ("api" or "web")
token_id	body	string	the ID identifying the generated token.
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	The region in which the user resides.
user_stack	body	string	The stack against which the user has authenticated.
username	body	string	login username.
version	body	string	Version.

Response Example

{
    "version": 3,
    "user_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "token": "eyJhbGciOiJSUzI1NiIsInRXcCI6IkpXVCJ9.eyJzZWVkaW5nIjoxNzU0MzE1OTA0LCJ2ZXJzaW9uIjozLCJ1c2VyX2lkIjoiMmZmMjE0YjYtMDg0Ny0xMWVmLTk2NDEtMzM0MDRkOWQ3MzY0IiwidXNlcl9kb21haW4iOiJpbnRlcnN0ZWxsaW8uaW8iLCJ0b2tlbl9pZCI6IjE2OWRmOWUwLTcxM2ItMTFmMC1iNTU5LTc5ZjEyMTA1OWEzMSIsImFwcCI6ImFwaSIsImNyZWF0aW9uX3RpbWUiOiIyMDI1LTA4LTA0VDEzOjU4OjI0LjQ5NFoiLCJ1c2VyX3N0YWNrIjoiemEtZ3AteG5sLTEiLCJ1c2VyX3JlZ2lvbiI6IlNvdXRoIEFmcmljYSIsInVzZXJfYWdlbnQiOiJSYXBpZEFQSS80LjMuNSAoTWFjaW50b3NoOyBPUyBYLzE1LjEuMSkgR0NESFRUUFJlcXVlc3QiLCJzb3VyY2VfaXAiOiIxMDIuMjIuMjQ3LjU3IiwibG9jYXRpb24iOiJBbGJlcnRvbiwgR2F1dGVuZywgU291dGggQWZyaWNhIiwibmFtZSI6ImFsZXhAaW50ZXJzdGVsbGlvLmlvIn0.SJJnj0aOY6abVhrinwwM6T-C54usF0lNmQUIGz8agTNCO6mhjsLDepJKap8ha6yjop2OgeJ0yDvarAo-7yC5rb7Ohbm8qluT2CEDeaMSQc6s_-W0gUybt2cgBZhNcV9L-3f9cn-eRfU3Qly131JkFfhuHLGIQTRAXmnV5LLNY9ok6Lg0444o6k7-wekk3bF21TvPcJLmi1vdP4G_7W-0LbySg-rRZwg6rAJdYghMO0MJ5UdbHyk_U2RcT00-xnQyNPvKTosa1V12Wbvr0iwzItipMEIZLInYrDckG6wIdKSeRVn1IGdaA_0XESCrzXaHieWLYbnTqnwnVZGEVkvXMAdzTUHRoRXdJTINApCd_zBiqlIZXtjMDrNut_6GpQBv5QWP9fpxT-iNyAD_9Z-7N47qMhH314y2Q4EjvqNrjYpdiuyRcu6LlQj04RPc6Y2ZqpFA0VlNk_h4b-0cH_tn77QdBBGaE4rRlr7LECSMPzYuTslZX2O44hnwUZt5Vf3pOjy9-F_nb4Uq9KU9t6ZYJZIIADw_sHL8eBylIUc7y_2ZI62a7sF9dV5qRFzGhH4jMP4pA9aRMrQxplrNoVwYhMzSerds7fD62JZjFnseqdfkJyETb916LxRcJwrccHM3GmjBfqqFR997XPLhduZEaYlK-mP54sVMvGFg2Ku7-FM",
    "token_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "token_app": "api",
    "creation_time": "2025-08-04T13:58:24.494Z",
    "user_region": "South Africa",
    "user_stack": "za-gp-xnl-1",
    "user_domain": "example.com",
    "username": "test@example.com",
    "name": "Test User",
    "user_defined_timezone": "Africa/Johannesburg",
    "roles": [
        "Subscriber Administrator",
        "Identity Administrator"
    ],
    "context": {
        "domain": "example.com",
        "tenant_id": null
    }
}