Deploy API Authentication

Heretto Deploy API ensures secure processing and delivery of your content for end-user consumption. Deploy API employs two API authentication methods to securely distribute content from Heretto CCMS to various delivery endpoints: Simple API Keys and JSON Web Tokens (JWTs). Both methods are managed as API keys within Heretto CCMS. API keys are also known as secret keys or secrets.
Simple API Key

A Simple API Key uniquely identifies an application, developer, or user to verify access permissions. It is a string of characters included in an API call or request header.

Simple API Keys can grant access to the entire CCMS Content Library or a specific map. Simple API Keys cannot be restricted to specific audiences. Within their configured scope, they always have full access to content across all audiences.

Simple API Keys grant access to every client and should not be used from the browser. Only use them for machine-to-machine communication.

Users assigned the Administrator role in Heretto CCMS can create and delete Simple API Keys.

JSON Web Token (JWT)

A JSON Web Token (JWT) is an open standard for securely sharing JSON data between parties. It verifies application access permissions and specifies access rights. Without an authentication system, the token is saved as a cookie and follows the user until the tab is closed.

For Deploy API purposes, before it's used in API calls, a JWT must be signed with a JWT HS256 key.

JWTs can grant access to the entire CCMS Content Library or a specific map. You can further refine user access through conditional profiling with DITAVALs in Heretto CCMS. For more information about profiling content for different audiences, see Deploy API Filtering and Personalization.

JWTs also enable you to embed content in another webpage or to build a website or web application.

Users assigned the Administrator role in Heretto CCMS can create and delete JWT HS256 keys required to create JWTs. They can also specify the access the tokens provide, for example, to the entire content set or to a particular map.

You can provide authentication for all endpoints in the HTTP header X-Deploy-API-Auth or as a URL parameter token. Both methods use the same value: either a Simple API Key or JWT (signed with a JWT HS256 key).

Figure 1. The Deploy API interface in Heretto CCMS with a number of API keys configured
Deploy API interface with list of API keys.

How the Audiences Claim and Requested Audience Work Together

Audience-based filtering applies only to JWT authentication. Simple API Keys are not restricted by audience.

The audiences claim in a JWT payload and the audience requested in an API call serve different purposes, and the content returned depends on both:

  • The audiences claim in the JWT payload determines which audiences the token is permitted to access.

  • The audience requested in the API call determines which audience the returned content belongs to.

audiences claim in the JWT

Audience requested in an API call

Audience returned

Empty ([])

Not specified or a specific audience (for example, private)

__default

Omitted, or set to null

Not specified

__default

Omitted, or set to null

A specific audience (for example, private)

That audience

A list naming specific audiences (for example, ["private"])

The same named audience (for example, private)

That audience

In short, a missing or null claim places no restriction on which audience can be requested. An empty claim restricts every request to __default, regardless of if or which audience is requested.

Configure Deploy API Authentication Process

You can configure Deploy API authentication with a method of your choice: a Simple API Key or JSON Web Token (JWT).

Portions of this process can be completed only by users assigned the Administrator role in Heretto CCMS.

  1. Obtain Parameter Values for Endpoint URLs

    You need two parameter values. You need to be assigned the Administrator role in the CCMS to get one of them.

  2. Create an API Key

    Both simple API keys and JWT HS256 keys are created in Heretto CCMS. You need to be assigned the Administrator role in the CCMS to complete this step.

  3. Create a JWT (JWT only)

    This step is required only for JWT authentication. If you are using Simple API Key, skip this step.

  4. Make Authenticated API Calls

    Configure authentication and test it by making an API call.

Obtain Parameter Values for Endpoint URLs

Each endpoint URL in Heretto Deploy API contains two variables that need to be replaced with actual values: organizationId and deploymentIdentifier. These variables are specific to your Heretto CCMS implementation.

Portions of this procedure can be completed only by users assigned the Administrator role in Heretto CCMS.

An example of the Search pages endpoint with both variables:

JSON 
https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/search

Ensure you are assigned the Administrator role in Heretto CCMS.

Obtain the organizationId parameter value

  1. Contact your Customer Success Manager (CSM) or the Heretto support team to get the organizationId parameter value.

Obtain the deploymentIdentifier parameter value (Administrators only)

  1. Log in to Heretto CCMS as an Administrator.
  2. In the top-left corner, click the Main Menu and go to Deployments.
  3. In the deployments list, click the name of the deployment you want to use in your API calls.
  4. In the Info section, copy the value in the ID field.
    The deploymentIdentifier is the value found in the ID field.
Create an API Key

Create an API Key

API keys are necessary for authorizing and authenticating users, and to call Heretto Deploy API endpoints. There are two API key types you can chose form: Simple API Key or JWT HS256 Key. For more information on API key types and authentication methods, see Deploy API Authentication.

This procedure can be completed only by users assigned the Administrator role in Heretto CCMS.

Important:

For production applications, never expose your secret keys in client-side code or third-party web tools.

Ensure you are assigned the Administrator role in Heretto CCMS.

  1. Log in to Heretto CCMS as an Administrator.
  2. In the top-left corner, click the Main Menu and go to Deploy API.
  3. Click the New API Key drop-down menu and select a key type:
    • Simple API Key
    • JWT HS256 Key
  4. In the window that opens, provide key details:
    1. In the Name field, enter a meaningful key name.

      For clarity, we suggest including map or deployment details in the key name.

    1. From the Access Type drop-down menu, select the access type for the key.

      The All Content option grants the token owner access to the entire Content Library. The Specific Map option grants the token owner access limited to a map of you choice.

  5. Click Save.

The new API key is listed in the Deploy API along with its type, name, and access.

Figure 2. The Deploy API interface in Heretto CCMS with a number of API keys configured
Deploy API with list of API keys.

If you created a Simple API Key, you are ready to make authenticated API calls. See Make Authenticated API Calls.

If you created a JWT HS256 key, you must create a JWT. See Create a JWT.

Create a JWT

Important:

For production applications, sign your JSON Web Token (JWT) server-side using appropriate libraries. Never expose your secret keys in client-side code or third-party web tools.

Create a JWT by specifying its header and payload, and signing it with your JWT HS256 key generated in Heretto CCMS.

This procedure provides the details you need to configure the header, payload, and signature of your JWT. It doesn't provide step by step instructions of how to do it in a specific tool or library.

Create a JWT HS256 key. See Create an API Key.

  1. In the header, set the algorithm to HS256 and token type to JWT.
    JSON 
    {
  "alg": "HS256",
  "typ": "JWT"
  }
  2. Configure the payload based on your access requirements:

    When configuring the payload, you must decide whether to include audience in it or not. When we refer to an audience in this context, we mean the audience configured directly in your main portal sitemap, not the values you use for the audience attribute in your DITAVAL files. For details, see Define Audiences in a Map.

    • For a configuration that maps audience to the __default value, use an empty payload:

      JSON 
      {}

    • For a configuration that uses a specific configured audience, add:

      JSON 
      {
  "https://jorsek.com/content/audiences": [
    "your_audience_name"
  ]
}

      Where your_audience_name is the value attribute of the <data> element with name="content-api-audience" in the main sitemap associated with your deployment. For example, if your sitemap contains:

      CODE 
      <data href="../filters/private.ditaval" name="content-api-audience" value="private"/>

      Use:

      JSON 
      {
  "https://jorsek.com/content/audiences": [
    "private"
  ]
}
  3. Sign the token with the JWT HS256 key created in Heretto CCMS.
  4. Generate the JWT.
    The token consists of three base64-encoded sections separated by dots: header.payload.signature
    JSON 
    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL2pvcnNlay5jb20vY29udGVudC9hdWRpZW5jZXMiOlsicHJpdmF0ZSJdfQ.b3DJPBQNkD-qY_0tbPIrqI-Dz6nbFVIBnIzWto_Nal4
Make Authenticated API Calls

Make Authenticated API Calls

Configure authentication to securely access deployment content. Test your setup by making an API call using either a Simple API Key or a JWT, based on your previous configuration.

Replace endpoint URL variables with actual values

  1. In the endpoint URL, replace the organizationId and deploymentIdentifier variables with the values you obtained.

    Search endpoint URL before variables are replaced:

    JSON 
    https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/search

    Search endpoint URL after variables are replaced:

    CODE 
    https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/search

Apply the authentication method

  1. Apply the authentication method of your choice in your API requests:
    Option Description

    Simple API Key

    Apply the key as generated in Heretto CCMS directly in your API requests using either the header or URL parameter method.

    Header Authentication

    CODE 
    curl --location 'https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/structure' \
--header 'X-Deploy-API-Auth: a59ac183a8bc4a848c92082f91b863dc'

    URL Parameter Authentication

    CODE 
    https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/structure?token=a59ac183a8bc4a848c92082f91b863dc

    JWT
    Warning:

    Use the JWT signed with a JWT HS256 key, NOT the original JWT HS256 key you generated in Heretto CCMS. The JWT must be signed with a JWT HS256 key first.

    Apply the signed JWT in your API requests using either the header or URL parameter method.

    Header Authentication

    CODE 
    curl --location 'https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/search' \
--header 'X-Deploy-API-Auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL2pvcnNlay5jb20vY29udGVudC9hdWRpZW5jZXMiOlsicHJpdmF0ZSJdfQ.x7KlW9Z5jS6ImF1ZGllbmNlX2Ei'

    URL Parameter Authentication

    CODE 
    https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/search?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL2pvcnNlay5jb20vY29udGVudC9hdWRpZW5jZXMiOlsicHJpdmF0ZSJdfQ.x7KlW9Z5jS6ImF1ZGllbmNlX2Ei

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

JSON 
{
    "status": "success",
    "data": {...}
  }

Common issues:

  • 401 Error: Verify that your API key or JWT is correct and not expired

  • 404 Error: Check that your organizationId and deploymentIdentifier are correct

  • Empty Response: Ensure you're using the correct endpoint for your deployment type

Last updated: October 9, 2026