API Authentication

Token Authentication (V1)

Once a user is authenticated, a token is generated for authorisation and access to a NebularStack environment. A token can have a variable life span; however, the default expiry value is one hour. The recommended expiry value is set to a low value that allows enough time to complete tasks.

In short, NebularStack uses JWT (JSON Web tokens), which is the proposed Internet standard for creating data with optional signature and/or optional encryption whose payload holds JSON that asserts some number of claims. The claims in our case would be role assignments and the current scoped domain and tenant. The tokens are signed using certificates. Any tampering with the token would invalidate it.

Using token authentication, you have un-scoped and scoped tokens. Scoped means the token has been generated for a specific domain or domain and tenant. Based on the roles assigned to the authenticated user for the domain and tenant, those roles are set within the token.

Tokens can be renewed anytime and re-scoped to another domain and tenant. During the re-scope or renewal, a newly updated token is provided. If your token is scoped to a domain and not within a tenant with sufficient roles to perform desired actions on all relevant tenants, you only need to use the X-Tenant-ID header on any requests in that domain to set the tenant-id for the request.

Token Authentication (V2)

In the same manner as the /v1/token API resource, /v2/token utilises JWTs (JSON Web Tokens).

During a successful authentication, both an authentication token and a refresh token are generated and returned in the authentication response.

Refresh tokens are used either to rescope an existing authentication token or to renew an expired authentication token. Refresh tokens are valid for 30 days, this lifetime is reset to 30 days when a refresh token is used to renew an expired authentication token, rescope an existing authentication token or a re-authentication occurs. A new refresh token will only be generated if the previous refresh token has expired.

Authentication tokens are used for authorisation and access to the NebularStack environment, by providing said token in the X-Auth-Token HTTP header when making HTTP requests to NebularStack. Authentication tokens are valid for 1 hour, after which a new token must be generated (either by re-authenticating, or renewing said token). An authentication token can be scoped to either a domain alone or both a domain and a tenant, furthermore an authentication token can be renewed or rescoped at anytime. Authentication tokens can be rescoped using either a refresh token or the authenticating users password. If a token is scoped to a domain and not within a tenant with sufficient roles to perform desired actions on all relevant tenants, one need only use the X-Tenant-ID header on requests in that domain to specify the tenant-id for said request.

An authentication token's type can be either "standard" or "minimal".

Standard authentication tokens contain all the roles assigned to the authenticating user, providing access as specified by the user's assigned roles on NebularStack. Additionally, an OTP must be provided when attempting to obtain a standard authentication token if the authenticating user has MFA enabled.

Minimal authentication tokens do not contain any roles, regardless of what roles are assigned to the authenticating user. These tokens provide only limited access to NebularStack, namely to API resources that do not require specific roles. Additionally, an OTP will never be required when attempting to obtain a minimal authentication token, even if the authenticating user has MFA enabled.

When renewing or rescoping an authentication token, the type of the authentication token will remain unchanged. Refreshing a standard authentication token will always yield a standard authentication token, while rescoping a minimal authentication token will always yield a minimal authentication token.

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

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

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

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

{
    "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.

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

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

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

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

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

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

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