Users and Usage Statistics API

This document details API endpoints related to user account management and retrieving system usage statistics. These endpoints cover operations on user accounts and system-wide usage data.

These endpoints allow interaction with user accounts, including retrieving, updating, and managing user-specific data and credentials.

With the statics we can check the active-users to see the size of the environment.

For documentation about the older version v1 it can be found here and for userInformartion here.

Core Resource Path

The core path segment for most User endpoints is:

api/v2/users

Endpoints related to user authentication actions (like password or 2FA reset) might reside under the auth/ path, even if managed in the user context.

Endpoints

The following endpoints are available for User management:

URL	HTTP Method	Description
/users	GET	Retrieves a list of users. Supports query parameters like limit for pagination or filtering. Example 2
/users/{userID}	GET	Retrieves the details of a specific user by their ID. Example 3
/users/{userID}/reference-data	GET	Retrieves specific reference data associated with a user account.
/users/{userId}/long-lived-tokens	POST	Generates or requests a new long-lived authentication token for the specified user. Requires appropriate permissions. Example 4
/auth/reset-password	POST	Initiates a password reset process. Requires user identification (e.g., email) in the body.
/auth/reset-2FA	POST	Resets the Multi-Factor Authentication (2FA) setup for a user. Requires appropriate permissions.
/usage-statistics/active-users	GET	Retrieves data or a count of currently active users in the system. Example 1

Examples

This section provides examples for some common operations using curl. Remember to replace placeholders like {userID}, {userId}, {limit}, and [Main API Domain] with actual values. You will need a valid Bearer token in the Authorization header for most endpoints.

Example 1: Getting Active Users Count via Script Call

This example demonstrates how to use the REST.call() function to retrieve the active users count.

// Example usage of the REST.call script to get active users
const endpoint = 'api/v2/usage-statistics/active-users';
const method = 'GET';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'environment-id': serverDocument._environmentId // Replace with your actual access token
};
const body = null; // GET requests typically have no body

REST.call(endpoint, method, headers, body);

or using curl:

curl -X GET "[Main API Domain]/api/v2/usage-statistics/active-users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "environment-id: serverDocument._environmentId"

This will return a value like:

{ status: 'ok', data: { activeUsers: 2 } } 

Example 2: Listing Users with a Limit

This example demonstrates how to retrieve a list of users, limiting the number of results returned.

curl -X GET "[Main API Domain]/api/v2/users?limit=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "environment-id: serverDocument._environmentId"

When one user is found and more available it will return something like this:

{
  status: 'ok',
  data: [
    {
      _id: '68303113fa82b1ec8b3d7c14',
      profile: [Object],
      globalEmails: [Array],
      username: 'newtestuser@user.user',
      _createdOn: '2025-05-23T08:25:55.991Z',
      _createdByUserId: '1YNEXKYkPnqk52Fzf',
      _lastModifiedOn: '2025-05-23T08:25:55.992Z',
      _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf'
    }
  ],
  pagination: {
    hasPrevious: false,
    hasNext: true,
    type: 'mongo',
    next: 'limit=1&exclude=%5B%22authentication%22%5D&after=68303113fa82b1ec8b3d7c14'
  }
}

Example 3: Getting Details for a Specific User

This example shows how to retrieve the full profile and details for a user using their ID.

curl -X GET "[Main API Domain]/api/v2/users/user_abc" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "environment-id: serverDocument._environmentId"

Gets one user with the correct id:

{
  status: 'ok',
  data: [
    {
      _id: '68303113fa82b1ec8b3d7c14',
      profile: [Object],
      globalEmails: [Array],
      username: 'newtestuser@user.user',
      _createdOn: '2025-05-23T08:25:55.991Z',
      _createdByUserId: '1YNEXKYkPnqk52Fzf',
      _lastModifiedOn: '2025-05-23T08:25:55.992Z',
      _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf'
    }
  ]
}

Example 4: Generating a Long-Lived Token for a User

This example shows how to request a long-lived authentication token for a specific user (requires appropriate permissions for the calling user).

curl -X POST "[Main API Domain]/api/v2/users/user_abc/long-lived-tokens" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "environment-id: serverDocument._environmentId"

Returns the status if it succeeded and data with the long-lived-tokens as an array:

{ status: 'ok', data: [] }