Basic Authentication

Basic Authentication enables API requests using a username and password or token. It is suitable for automated workflows and server-to-server integrations.

Basic Authentication is a simple authentication scheme built into the HTTP protocol that enables you to authenticate API requests using your Heretto CCMS username and password (or token, recommended). This method is reliable for automated workflows, server-to-server integrations, and any scenario requiring programmatic access without browser interaction.

With Basic Authentication, you send your credentials with each API request in an Authorization header. Your username and password (or token, recommended) are combined with a colon (username:password), encoded using base64, and sent with the word Basic in the header. The server verifies your credentials and processes the request if they're valid.

Basic Authentication requires your Heretto CCMS username and either your password or an API token:

  • Username: Your CCMS account username (your email address)

  • Password or Token: When single sign-on (SSO) is configured in the CCMS, you have to generate a token. Otherwise, you can use your CCMS password. However, for security reasons, using a token is strongly recommended regardless of whether SSO is configured.

Important:

For security reasons, using an API token is strongly recommended regardless of whether SSO is configured. Tokens offer several advantages: they can be revoked independently, limited in scope, and rotated regularly without affecting your password.

Basic Authentication Process

Use your Heretto CCMS username and password or a token generated in the CCMS to authenticate. This process explains how to authenticate with a token.
  1. Generate a token in Heretto CCMS.

    When single sign-on (SSO) is configured in the CCMS, you have to generate a token. Otherwise, you can use your CCMS password. However, for security reasons, using a token is strongly recommended regardless of whether SSO is configured.

  2. Generate the authorization header.

    You need to encode your credentials in the base64 format. When using a token, use your username and token in the format username:token.

  3. Get a resource UUID.

    Resource UUID is the value you need for the file-id parameter. You can get it from the CCMS interface.

  4. Make authenticated API calls.

Generate a Token

You can generate a token to authenticate API requests instead of using your Heretto CCMS password. Use this token with any tool or application that makes API calls (such as cURL, WebDAV, Postman, or custom scripts).

Create separate tokens for different applications or scripts. This enables you to revoke a token without affecting other integrations.

When single sign-on (SSO) is configured in the CCMS, you have to generate a token. Otherwise, you can use your CCMS password. However, for security reasons, using a token is strongly recommended regardless of whether SSO is configured.
  1. Sign in to Heretto CCMS.
  2. In a web browser, navigate to https://organizationId/tools/token-management/tokens.xql

    Where {organizationId} is the subdomain you use to access Heretto CCMS. For example, if you access Heretto CCMS at https://thunderbird.heretto.com, use thunderbird as the organizationId.

    https://thunderbird.heretto.com/tools/token-management/tokens.xql
  3. In the Token name field, add a meaningful name for the token.

    The name will be visible in the tokens interface.

    Oxygen Webdav Token, or CI/CD Pipeline, or Publishing Script

  4. Click create token.
  5. Copy the login and password (token) information and keep it in a secure place.
    Important:

    Once you navigate away from the page with your login and token, you won't be able to see the token again.

Your token is now active. It will remain active until you manually invalidate it.

Invalidate a Token

You can invalidate a token you previously generated for API authentication. Once your token is invalidated, any API requests using that token will fail, regardless of the tool or application making the request (such as cURL, WebDAV, Postman, or custom scripts).

  1. Sign in to Heretto CCMS.
  2. In a web browser, navigate to https://organizationId/tools/token-management/tokens.xql

    Where {organizationId} is the subdomain you use to access Heretto CCMS. For example, if you access Heretto CCMS at https://thunderbird.heretto.com, use thunderbird as the organizationId.

    https://thunderbird.heretto.com/tools/token-management/tokens.xql
  3. Click Invalidate next to the token you no longer need active.
Your token is now inactive. Your API requests that use the invalidated token will fail.

Generate an Authorization Header

You need to encode your credentials in base64 format. When using a token, use your username and token in the format username:token.

Manual Generation - Command Line (Unix/Mac/Linux)

  1. Generate an authentication header for Unix, Mac, or Linux:
    CODE 
    echo -n "username:password_or_token" | base64

    Example with password:

    CODE 
    echo -n "demo:p@55w0rd" | base64
# Output: ZGVtbzpwQDU1dzByZA==

    Example with token:

    CODE 
    echo -n "demo:hrt_abc123XYZ456" | base64
# Output: ZGVtbzpocnRfYWJjMTIzWFlaNDU2

Manual Generation - Windows PowerShell

  1. Generate an authentication header for Windows PowerShell:
    POWERSHELL 
    [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("username:password_or_token"))

    Example with password:

    POWERSHELL 
    [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("demo:p@55w0rd"))
# Output: ZGVtbzpwQDU1dzByZA==

    Example with token:

    POWERSHELL 
    [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("demo:hrt_abc123XYZ456"))
# Output: ZGVtbzpocnRfYWJjMTIzWFlaNDU2

Online Base64 Encoders

  1. You can use online tools like base64encode.org, but be cautious about entering real passwords or tokens into third-party websites. Only use for testing with temporary credentials.

Get a Resource UUID

Each resource in Heretto CCMS has its own Universally Unique Identifier (UUID). UUIDs are essential when working with Heretto CCMS API and are also useful in other scenarios, such as referencing resources like graphics or custom fonts in PDF Generator publishing configurations.

  1. In the Content Library, click a resource.
    The Resource Drawer opens on the right.
  2. At the bottom of the resource drawer, click API Info and copy the contents of the UUID field.
    a gif showing a user clicking on a map, Resource Drawer opening on the right, user going to API Info section and selecting resource UUID

Make Authenticated API Calls

With authentication set up, you are ready to test your setup by making an API call using your username and token.

To make calls for specific files, you need the file-id parameter value (UUID) that you can get from the CCMS interface

Replace Endpoint URL Variables

  1. All CCMS API endpoints use this base URL structure: https://{organizationId}.heretto.com/ezdnxtgen/api. Replace the organizationId variable with your CCMS subdomain.

    If you access Heretto CCMS at https://thunderbird.heretto.com, use thunderbird as the organizationId.

    Before:

    JSON 
    https://{organizationId}.heretto.com/ezdnxtgen/api/v2/deployments

    After:

    CODE 
    https://thunderbird.heretto.com/ezdnxtgen/api/v2/deployments

Apply Basic Authentication

  1. Include the Authorization header with your base64-encoded credentials in each API request.

    Header format:

    CODE 
    Authorization: Basic <base64_encoded_username:token>

    cURL example:

    CODE 
    curl -X GET \
  'https://thunderbird.heretto.com/ezdnxtgen/api/v2/deployments' \
  -H 'Authorization: Basic ZGVtbzpocnRfYWJjMTIzWFlaNDU2'

A successfully authenticated request returns a 200 status code with the requested content. An example of a successful response is:

JSON 
{
  "content": [
    {
      "id": "deployment-123",
      "name": "Product Documentation",
      "type": "manual",
      "lastUpdated": "2025-11-24T10:30:00Z"
    }
  ],
  "number": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}