Authentication and Security

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 grant access to every client and should not 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 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).

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

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.

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.
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.
Create a JWT (JWT only)
This step is required only for JWT authentication. If you are using Simple API Key, skip this step.
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:

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

Ensure you are assigned the Administrator role in Heretto CCMS.

Obtain the organizationId parameter value

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

Obtain the deploymentIdentifier parameter value (Administrators only)

Log in to Heretto CCMS as an Administrator.
In the top-left corner, click the Main Menu and go to Deployments.
In the deployments list, click the name of the deployment you want to use in your API calls.
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

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 Authentication and Security.

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.

Log in to Heretto CCMS as an Administrator.
In the top-left corner, click the Main Menu and go to Deploy API.
Click the New API Key drop-down menu and select a key type:
- Simple API Key
- JWT HS256 Key
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.
Click Save.

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

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

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.

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

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.

In the header, set the algorithm to HS256 and token type to JWT.
```
{
  "alg": "HS256",
  "typ": "JWT"
  }
```
Configure the payload based on your access requirements:
- For basic access that grants access to all content included in the deployment, use an empty payload:
```
{}
```
  Note:
  When your JWT doesn't have an audience value embedded, requests are mapped to the default audience.
- For audience-based content filtering, add:
```
{
  "https://jorsek.com/content/audiences": [
    "your_audience_name"
  ]
}
```
  Where your_audience_name is the value attribute in the data element referencing a DITAVAL file in the main sitemap associated with your deployment. For example, if your sitemap contains:
```
<data href="../filters/private.ditaval" name="content-api-audience" value="private"/>
```
  Use:
```
{
  "https://jorsek.com/content/audiences": [
    "private"
  ]
}
```
  Note: If the value attribute is not specified in your sitemap data element, use an empty payload {}.
Sign the token with the JWT HS256 key created in Heretto CCMS.

Generate the JWT.

The token consists of three base64-encoded sections separated by dots: header.payload.signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWRpZW5jZSI6InlvdXJfYXVkaWVuY2VfbmFtZSJ9.b3DJPBQNkD-qY_0tbPIrqI-Dz6nbFVIBnIzWto_Nal4

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.

Obtain your organizationId from your Customer Success Manager (CSM) and your deploymentIdentifier from the Deployments interface. See Obtain Parameter Values for Endpoint URLs.
Create either a Simple API Key or JWT HS256 Key in Heretto CCMS. See Create an API Key.
If using JWT, create your JWT. See Create a JWT.

Replace endpoint URL variables with actual values

In the endpoint URL, replace the organizationId and deploymentIdentifier variables with the values you obtained.
Search endpoint URL before variables are replaced:
```
https://{organizationId}.deploy.heretto.com/v4/deployments/{deploymentIdentifier}/search
```
Search endpoint URL after variables are replaced:
```
https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/search
```

Apply the authentication method

Apply the authentication method of your choice in your API requests:

Option Description

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 `curl --location 'https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/structure' \ --header 'X-Deploy-API-Auth: a59ac183a8bc4a848c92082f91b863dc'` URL Parameter Authentication `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 `curl --location 'https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/search' \ --header 'X-Deploy-API-Auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWRpZW5jZSI6ImF1ZGllbmNlX2EifQ.x7KlW9Z5jS6ImF1ZGllbmNlX2Ei'` URL Parameter Authentication `https://thunderbird.deploy.heretto.com/v4/deployments/I9vA3KlK1331IYmEHhU/search?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWRpZW5jZSI6ImF1ZGllbmNlX2EifQ.x7KlW9Z5jS6ImF1ZGllbmNlX2Ei`

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

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

URL Parameter Authentication

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

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

URL Parameter Authentication

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

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

{
    "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

Under maintenance

Heretto Help