Show Page Sections

Authentication and Security

Heretto Deploy API ensures that your content is processed in a secure way and delivered to the defined users. This information explains our authentication and security.

Deploy API uses two different methods of API authentication to ensure the secure distribution of content from Heretto CCMS to various endpoints, Simple API Keys and JSON Web Tokens (JWTs). We manage both as API Keys in the Content API interface of Heretto CCMS. For instructions, see Create API Keys.

Simple API Key
A Simple API Key gives the same access to every website or web application user.
JSON Web Token (JWT)
A JSON Web Token (JWT) enables you to specify user access based on maps and DITAVALs

Simple API Keys

A Simple API Key is a unique identifier used to verify that an application, developer, or user has permission to access the other application. The key is a long string of characters passed as a parameter in an API call or included in the request header.

Simple API Keys give the same access to every website or web application user.

Heretto CCMS Administrators can create and delete Simple API Keys.

JSON Web Tokens (JWTs)

A JSON Web Token (JWT) is a self-contained token that not only verifies that the application has permission to access another application but also provides additional information that specifies the granularity of access rights. If you use a JWT security method that does not include an authentication system, the token is saved as a cookie and follows the user until they close the tab.

JWTs enable you to specify user access based on maps. You can further refine user access through conditional profiling with DITAVALs. For more information about profiling content for different audiences, see Audiences.

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

Heretto CCMS Administrators can create and delete JSON Web Tokens (JWTs). They can also specify the access the tokens provide, for example, to the entire content set or to a particular map.

API Call Authentication

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: the API Key provided in the Content API interface interface in Heretto CCMS.


The Content API interface is available for users added in the Administrator role to Heretto CCMS.

Figure 1. Content API interface
Content API interface with list of API keys.

Create API Keys

Use Heretto interface to create API Keys. API Keys are necessary for authorizing and authenticating users, and to call Heretto Deploy API endpoints.

  1. In the top-left corner, click the Main Menu and go to Content API.
  2. Click the New API Key and choose:
    • Simple API Key
    • JWT HS256 Key

    A new dialog window opens.

  3. Enter a name for the token.
  4. From the Access Type choose:
    • Select All Contentto grant the token owner access to the entire Content Library.

    • Specific Map, then click the Add file, and select a map. To grant the token owner limited access to an individual map.

  5. Save.

Find Values of Heretto-Specific API Attributes

Heretto Deploy API requires you to enter values of some attributes that are are specific to your implementation of Heretto CCMS.


In the current version of Heretto, to obtain your organizationId or Deploy API server name, contact your Customer Success Manager or our support team.


To find the value of deploymentId, access the Main Menu , click Deployments, and click the name of the required deployment. The deploymentId is the value of the ID field.