Authentication API

Before you can request data via a REST call you need to have an authentication token. To get this token you can use one of the tools described on this page.

This document details the API endpoints used for user authentication within the application. These endpoints are crucial for securing access and are typically used before performing actions that modify documents or require user identification. The authentication primarily uses Bearer tokens obtained through the login process.

For more information about v1 check this documentation.

Base URL

For the authentication for v2 this API endpoint is used:

api/v2/auth

Endpoints

The following endpoints are available for Authentication, relative to the Base URL (api/v2/auth):

URL	HTTP Method	Description
/login	POST	Authenticates a user using credentials (e.g., username/email and password) and returns authentication tokens. Could be gathered using curl as show in Example1 or with REST.call as shown Example 2.
/token	GET	Exchanges a valid refresh token for a new access token and a new refresh token. The refresh token is sent in the x-refresh-token header. See Example 3 and Example 4.

Examples

This section provides examples for common authentication workflows.

Example 1: User Login

This example shows how to authenticate a user using their email and password to obtain access tokens.

curl -X POST "[Main API Domain]/api/v2/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "securepassword123"
  }'

If the user can be found, an object like this will be sent:

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "userId": "string",
  "isBizzStreamSupport": false,
  "defaultEnvironmentId": "string",
  "expires_in": 43200,
  "refresh_expires_in": 604800
}

Use the accessToken as a Bearer token in the Authorization header of your other requests (Authorization: Bearer YOUR_ACCESS_TOKEN). The other fields tell you how long the tokens are valid:

Field	Description
expires_in	Lifetime of the access token in seconds (43200, which is 12 hours).
refresh_expires_in	Lifetime of the refresh token in seconds (604800, which is one week).

Two-factor authentication

If the user needs two-factor authentication, the login response contains preAuthToken, url2FA and needs2FA instead of the tokens above.

Example 2: Getting a Bearer Key using REST.call

For most calls, getting an bearer key is the first step. This makes getting this key very important to correctly understand and use. It is good to note that the return value is still the same as the first example. Below, you will find information on how to get the key from the current user using REST.call:

const loginEndpoint = `${API_server}/api/v2/auth/login`;// Fill API_server in with actual server
const loginMethod = 'POST';
const loginHeaders = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
};
const loginBody = {
  username: 'user', // actual name needs to be entered
  password: 'password' // actual password needs to be entered
};

// Call the API using the REST.call function
const authToken = REST.call(loginEndpoint, loginMethod, loginHeaders, loginBody);
console.log(authToken);

Using the refresh token

An access token is valid for 12 hours. Instead of logging in again with the username and password, you can use the refreshToken from the login response to get a new access token. This is mainly useful for long-running external integrations, because they do not have to keep the password around.

How it works:

1. Log in once and store the accessToken and the refreshToken.
2. Use the access token until it is about to expire (see expires_in).
3. Call GET /token with the refresh token in the x-refresh-token header. There is no request body and no query parameter.
4. Store the new accessToken and the new refreshToken from the response, and use the new refresh token the next time.

Every refresh returns a new access token and a new refresh token. A refresh token is valid for one week from the moment it was issued, so an integration that refreshes regularly never has to send the password again. If the refresh token has expired because you did not refresh within a week, log in again with the username and password.

Response format

Unlike /login, the response of /token is wrapped in the standard response object with status and data.

Do not log in on every call

Each login and each refresh registers a new token pair on the user. Reuse the access token until it is about to expire and then refresh it. For a server script that runs occasionally, such as a scheduled action, it is fine to log in once per run and reuse the access token for all calls in that run.

Example 3: Refreshing an access token

curl -X GET "[Main API Domain]/api/v2/auth/token" \
  -H "Accept: application/json" \
  -H "x-refresh-token: YOUR_REFRESH_TOKEN"

The response looks like this:

{
  "status": "ok",
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expires_in": 43200,
    "refresh_expires_in": 604800
  }
}

Example 4: Refreshing an access token using REST.call

const refreshEndpoint = `${API_server}/api/v2/auth/token`;// Fill API_server in with actual server
const refreshMethod = 'GET';
const refreshHeaders = {
  'Accept': 'application/json',
  'x-refresh-token': refreshToken // the refreshToken you received from the login or the previous refresh
};

// Call the API using the REST.call function, a GET request has no body
const result = REST.call(refreshEndpoint, refreshMethod, refreshHeaders, null);

const newAccessToken = result.data.accessToken;
const newRefreshToken = result.data.refreshToken; // store this one, use it for the next refresh