Authentication

Authenticate your user when using the API.

The API supports several authentication methods. Choose the one that best fits your integration scenario.

The API uses personal access tokens to authenticate requests. By default, tokens expire after 24 hours — if you need a longer-lived token, see Long-lifetime access tokens.

You can view and manage your access tokens on the My Profile page, in the section titled Developer Settings.

Bearer authentication

API requests are authenticated using the Bearer Auth scheme.

To authenticate a request, provide the token in the Authorization header of the request.

Access tokens are tied to the user account for which they were created. A token provides the same level of access and permissions privileges that its associated user account would have in the user interface.

Warning

Please remember to keep your API access token secure! Do not share your token in emails, chat messages, client-side code, or publicly accessible sites.

If you have accidentally shared your access token publicly, you can revoke it (and issue a new token for your account) in the Developer Settings of your user account by clicking the refresh icon beside the token.

Cookie authentication

Most API endpoints support both Bearer authentication and Cookie authentication.

Secure cookie authentication may be preferred in some specific integration scenarios. For example, if you are using the platform in headless mode, and if you are building your own user interface with a library such as React, then you might prefer cookies over bearer tokens for authenticating HTTP requests that originate with your (authenticated) users.

Authentication cookies incorporate several security features to protect user data and prevent unauthorized access. These security features include the following:

• The Secure flag ensures the cookie is only transmitted over encrypted HTTPS connections, preventing interception during communication between clients and the server.
• The HttpOnly attribute prevents client-side scripts from accessing the cookie through JavaScript, mitigating cross-site scripting (XSS) attacks.
• The SameSite attribute helps prevent cross-site request forgery (CSRF) attacks by restricting the cookie to same-site contexts or explicitly allowing cross-site usage.
• An expiration date limits the cookie's lifespan.
• Domain and path restrictions limit where the cookie can be used and where it can be accessed.
• The cookie value is signed with a cryptographically secure digital signature, and then encrypted for additional privacy and security.

Client secret authentication

A small number of specific API endpoints support Client Secret authentication.

An OAuth 2.0 client secret is not a fixed format, but rather a string of characters, typically a long, randomly generated sequence. It's a confidential credential that is known to (and shared by) your application and the server.

Info

A typical client secret might look like this: wJalrXUtnFEMI0O6JX5MCkmbs6JqPcx3

Every developer account is assigned a client secret that is generated by the system. You can see the client secret assigned to your account on the My Profile page, in the section titled Developer Settings. For a practical example of using your client secret, see Long-lifetime access tokens.

To authenticate a request, provide the secret in the Authorization header of the request. Please note the header value must include the word Secret as a prefix. For example:

Secret wJalrXUtnFEMI0O6JX5MCkmbs6JqPcx3

Client secrets are generated using cryptographically strong random number generators, ensuring they have sufficient entropy to resist brute-force attacks and are statistically unique across different client applications.

• The secrets are typically long, random strings that are computationally infeasible to guess or derive through cryptanalysis.
• The secrets are designed to be treated as sensitive credentials with proper lifecycle management, including secure generation, storage, rotation, and revocation capabilities.

Client secret authentication is limited in scope because it requires the ability to securely store and protect the secret, which is feasible only for confidential clients like server-side applications. Bearer tokens have more sophisticated security features (e.g., shorter lifespans, scoped permissions, easy revocation) — this is why bearer authentication is preferred and required for most API endpoints throughout the platform.

Long-lifetime access tokens

By default, API access tokens expire after 24 hours. For automated processes, scheduled tasks, or long-running integrations, you can generate a token with an extended lifetime by invoking a specific endpoint with your API Client Secret.

Endpoint

POST /v2/{partition}/security/tokens/generate

Request body

Property	Type	Description
Secret	string	Your API client secret
Lifetime	integer	Token lifetime in seconds

Common lifetime values

Duration	Seconds
1 hour	3600
1 day	86400
30 days	2592000
1 year	31536000

Examples

curl (Linux / macOS)

curl -X POST "https://sandbox-hub.cmds.app/v2/e99/security/tokens/generate" \
    -H "Content-Type: application/json" \
    -d '{
        "Secret": "your-api-client-secret",
        "Lifetime": 31536000
    }'

PowerShell (Windows)

$url = "https://sandbox-hub.cmds.app/v2/e99/security/tokens/generate"

$json = @'
{
    "Secret": "your-api-client-secret",
    "Lifetime": 31536000
}
'@

curl.exe -X POST $url `
    -H "Content-Type: application/json" `
    -d $json

Response

A successful request returns a JSON object containing your access token:

{
    "AccessToken": "eyJhbGciOiJIUzI1NiIs...",
    "TokenType": "Bearer",
    "ExpiresIn": 31536000,
    "Lifetime": "31,536,000 seconds (~52 weeks)"
}

If the secret is invalid or expired, the endpoint returns 401 Unauthorized. If the requested lifetime is out of the allowed range (1 minute to 1 year), the endpoint returns 400 Bad Request.

Secret expiry and token lifetime

A client secret expires 90 days after it is created. However, the lifetime of a generated access token is independent of the secret's expiry.

• A valid secret can generate an access token with a lifetime between 1 minute and 1 year.
• Once generated, an access token remains valid for its full lifetime even if the secret expires afterward.
• An expired secret cannot be used to generate new access tokens.

For example, you can use a secret to generate a one-year token on day 89. The secret expires the next day, but the token continues to work for the full year.

Security considerations

• A generated token inherits the full permissions of the user account that created it — treat it with the same care as your account credentials.
• Remember to store long-lived tokens securely.
• Use the shortest lifetime that meets your requirements.
• Rotate tokens periodically, even before they expire.
• Revoke tokens immediately if compromised.