1. Creating and using API tokens

API Tokens Overview

API tokens are long-lived authentication credentials designed for secure server-to-server integrations, automated processes, and third-party applications.

Key benefits:

• Long validity period (10 years by default)

• Persistent authentication without frequent login requirements

• Ideal for scheduled tasks, integrations, and backend services

• Same permission level as the creating user

Security considerations:

• Store API tokens securely as they provide extended access to your account

• Use environment variables or secure vaults rather than hardcoding tokens

• Implement token rotation practices for critical systems

Step 1 - Authenticate user to obtain a session token (Optional)

Before creating an API token, you need to authenticate with your username and password to obtain a session token. This step is only required once to generate the API token.

If you already have a valid API token from a previous operation, you can skip this step and use that token directly.

Endpoint

POST /login

Request

POST /login

Content-Type: application/json

{
  "name": "mary.griffin@circularo.com",
  "password": "#32Password1!",
  "returnToken": true
}

Response

{
  "logged": true,
  "isUnlocked": true,
  "token": "ZmgVNhyebGgAkzBtjFW3VhHStJObvat5w2dZmKPuWGUA36be9gsoZdoV741BpipH",
  "tenant": "default",
  "user": {
    ...
  },
  "settings": {
    ...
  },
  "rights": [
    ...
  ],
  ...
}

The response contains the following important properties:

• token - Located at token in the response.

  • The authentication token that should be included in subsequent API requests. This token identifies your session and provides access to authorized resources.

  • Example value: ZmgVNhyebGgAkzBtjFW3VhHStJObvat5w2dZmKPuWGUA36be9gsoZdoV741BpipH

Authentication successful. The response includes a session token that will be used in the next step to create an API token.

If your account uses Multi-Factor Authentication (MFA), you must complete the MFA challenge to unlock the token before proceeding with API token creation.

Step 2 - Generate a long-lived API token for server-to-server authentication

Creates a new API token for the authenticated user. This token is designed for server-to-server integrations and automated processes where persistent authentication is required.

• The token inherits all permissions from the creating user

• The token will be valid for 10 years by default

• Each user can have multiple active API tokens simultaneously

Endpoint

POST /api/key

Request

POST /api/key?token=ZmgVNhyebGgAkzBtjFW3VhHStJObvat5w2dZmKPuWGUA36be9gsoZdoV741BpipH

Content-Type: application/json

{
  "description": "API token for server-to-server authentication"
}

Response

{
  "id": "EFevvxRFfbFBqmcD27gIQl7Y6dtmd1JQPcbDd1tjwtacBoXNtWaglcwoV3MOqZwF"
}

The response contains the following important properties:

• apiToken - Located at id in the response.

  • The unique API token identifier that should be used for authentication in subsequent API calls. This token has the same permissions as the user who created it and is valid for 10 years.

  • Example value: EFevvxRFfbFBqmcD27gIQl7Y6dtmd1JQPcbDd1tjwtacBoXNtWaglcwoV3MOqZwF

The API token has been successfully created and can now be used for authentication.

Usage instructions:

• Include the token in API requests using the same parameter as a regular session token

• The token will remain valid for 10 years from creation

• The token has the same permissions as the user who created it

• To invalidate a token before expiration, use the token revocation endpoint

For security reasons, implement proper token management practices including secure storage, minimal permission scopes, and regular rotation for production systems.

Step 3 - Terminate the session token (Optional)

If you no longer need the session token after creating your API token, you can log out to invalidate it.

This only invalidates your session token, not the newly created API token which will remain active.

Endpoint

GET /logout

Request

GET /logout?token=ZmgVNhyebGgAkzBtjFW3VhHStJObvat5w2dZmKPuWGUA36be9gsoZdoV741BpipH

The session token has been successfully invalidated. Your API token remains active and can be used for authentication.

Step 4 - Test the API token by retrieving available documents (Optional)

This endpoint demonstrates how to use your newly created API token to perform an actual operation - in this case, searching for available documents in the system.

• The API token is passed in the query parameters just like a session token

• The search operation returns documents the authenticated user has access to

• This pattern applies to all API endpoints - simply use your API token instead of a session token

This is a practical example of how to use your API token for real operations. Do not call this endpoint if you don't wish to perform a search operation.

Endpoint

POST /search

Request

POST /search?token=EFevvxRFfbFBqmcD27gIQl7Y6dtmd1JQPcbDd1tjwtacBoXNtWaglcwoV3MOqZwF

Content-Type: application/json

{
  "from": 0,
  "size": 10
}

Response

{
  "from": 0,
  "total": 224,
  "results": [
    {
      "documentId": "fbaea99c-2747-47e5-ab1a-1ab42b015c58",
      ...
    },
    ...
  ],
  "users": {
    ...
  },
  ...
}

The search operation was successful, demonstrating that your API token is working correctly.

The response includes a list of documents that the authenticated user has access to.

API Token Usage Summary

The API token can now be used instead of a regular session token for all API operations.

• This token has the same rights as the user who created it

• Standard validity period is 10 years from creation date

• Use the token in the same way as session tokens in API requests

Example API Usage

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

// Create and use API token
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";

const name = "YOUR_NAME/EMAIL";
const password = "YOUR_PASSWORD";

try {
    // Step 1: Login to get session token
    const loginResponse = await fetch(`${URL}${API_PATH}/login`, {
        method: 'POST',
        body: JSON.stringify({ name, password, returnToken: true }),
        headers: { 'Content-Type': 'application/json' }
    });
    if (!loginResponse.ok) {
        throw new Error(`Login failed: ${loginResponse.status} ${loginResponse.statusText}`);
    }
    const { token } = await loginResponse.json();

    // Step 2: Get API token
    const apiTokenResponse = await fetch(`${URL}${API_PATH}/api/key?token=${token}`, {
        method: 'POST',
        body: JSON.stringify({ description: "API token for server-to-server authentication" }),
        headers: { 'Content-Type': 'application/json' }
    });
    if (!apiTokenResponse.ok) {
        throw new Error(`API Token fetch failed: ${apiTokenResponse.status} ${apiTokenResponse.statusText}`);
    }
    const { id: apiToken } = await apiTokenResponse.json();

    // Step 3: Logout the session token
    await fetch(`${URL}${API_PATH}/logout?token=${token}`);

    // Step 4: Use API token to fetch the documents (illustrative purpose)
    const searchResponse = await fetch(`${URL}${API_PATH}/search?token=${apiToken}`, {
        method: 'POST',
        body: JSON.stringify({ from: 0, size: 10 }),
        headers: { 'Content-Type': 'application/json' }
    });
    if (!searchResponse.ok) {
        throw new Error(`Search operation failed: ${searchResponse.status} ${searchResponse.statusText}`);
    }
    const result = await searchResponse.json();

} catch (error) {
    console.error('Error in API Token flow:', error.message);
}