Authentication and Security
- 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).
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
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
Obtain the deploymentIdentifier parameter value (Administrators only)
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.
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:
- Click Save.
The new API key is listed in the Deploy API along with its type, name, and access.
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
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.
Make Authenticated API Calls
-
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
Apply the authentication method
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