API Authentication

It's crucial to grasp the context of the domain and tenant in every request. This understanding is key to navigating the system effectively. For a comprehensive understanding, please refer to the Regions, domains and tenants from the User Guidelines.

API Key / Token Authentication

Once a user is authenticated, a token is generated for authorization and access to a NebularStack environment.

In short, NebularStack uses JWT (JSON Web tokens), which is the proposed Internet standard for creating data with optional signature whose payload holds JSON that asserts some number of claims. The tokens are signed using certificates. Any tampering with the token would invalidate it.

The life span of an unused token is 12 months, however you can purge a token using the API or simply manage them via our web frontend.

This endpoint should not be called often. Once you have a working API key you can safely reuse it for subsequent requests until it expires or is deleted.

We recommend that you create and manage your API keys from our console (UI) interface. For external integrations we recommend you create a dedicated user with the relevant roles assigned on the applicable domains or tenants, and create an API key for that user from the console (UI). Each identity user is limited to a maximum of 10 API keys.

Once an API key is deleted it will cease to work immediately, and any request using it will be rejected.

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
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
context	body	object	the domain and tenant to which the authenticated user is currently scoped.
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
X-Domain	header	string	Optional domain context for the request. (default: the token domain)

Response Status Codes

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