Skip to content

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 integrations, authenticate with a long-lived token instead of logging in with a username and password on every call. Use /login only for interactive or short-lived use.

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. Intended for interactive or short-lived use; integrations should use a long-lived token. 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 useful for a session that started with /login. For integrations, a long-lived token is the recommended option.

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

Long-lived tokens for integrations

A long-lived token lets an integration call the REST API without logging in with a username and password. Create one token per integration, store it securely, and send it along with every request.

  • A token belongs to a user and acts with that user's permissions.
  • A token is scoped to the environment it was created in. If you send an environment-id header, it must match that environment.
  • A token is valid for 90 days and cannot be extended. Rotate it before it expires.
  • Deleting a token revokes it immediately.

An administrator of the environment, or a consultant with access to it, can create, view and delete long-lived tokens for any user in that environment.

Creating a long-lived token

In the setup section: go to Users, open the user, and select the Access tokens tab. Click New, enter a name for the token in the Create access token window, and click Ok. The token is shown only once, so copy it and store it securely before you close the window.

Via the API:

curl -X POST "[Main API Domain]/api/v2/users/{userId}/long-lived-tokens" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "environment-id: YOUR_ENVIRONMENT_ID" \
  -d '{
    "name": "My integration"
  }'

The response contains the new token. It cannot be retrieved again later.

{
  "status": "ok",
  "data": {
    "token": "eyJhbGciOi..."
  }
}

Using a long-lived token

Send the token in the same header as an access token:

API Header
v2 Authorization: Bearer YOUR_LONG_LIVED_TOKEN
v1 x-auth-token: YOUR_LONG_LIVED_TOKEN
curl -X GET "[Main API Domain]/api/v2/users?limit=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LONG_LIVED_TOKEN" \
  -H "environment-id: YOUR_ENVIRONMENT_ID"

Listing and deleting long-lived tokens

The tokens of a user are listed on the Access tokens tab of that user, where you can also delete them with Revoke. Via the API:

URL HTTP Method Description
/api/v2/users/{userId}/long-lived-tokens GET Lists the user's long-lived tokens in the current environment, with their _id, name and _createdOn. The tokens themselves are not returned.
/api/v2/users/{userId}/long-lived-tokens DELETE Deletes the token with the _id given as tokenId in the request body, e.g. { "tokenId": "..." }. The token stops working immediately.

Rotating a long-lived token

  1. Create a new token for the integration.
  2. Switch the integration over to the new token.
  3. Delete the old token.

Rotate the token before its 90 days are up; an expired token is rejected.