HMAC

Hash-based Message Authentication Code (HMAC) provides strong security for Optimizely Graph requests by ensuring message integrity and authenticity. It combines a secret key with a cryptographic hash function, making it suitable for applications that handle sensitive data, such as financial services. HMAC protects communications from unauthorized access and tampering.

Include the HMAC values in the Authorization header using the following format:

Authorization: epi-hmac APP_KEY:TIMESTAMP:NONCE:SIGNATURE

Use your APP_KEY and SECRET credentials to implement HMAC.

HMAC query behavior

When you authenticate requests using HMAC, Optimizely Graph returns content based on the following default rules:

• The content is not deleted (_deleted = false).
• The content has not expired (StopPublish is null or set to a future date).

By default, querying with HMAC is equivalent to querying as a super user. Optimizely Graph returns all content regardless of publication status or role-based access control (RBAC) restrictions.

Modify query behavior with request headers

Include specific request headers to change how Optimizely Graph evaluates access and filtering. These headers enforce RBAC rules or include content that Optimizely Graph normally excludes.

Apply role-based access control (RBAC)

Use the cg-username and cg-roles headers together to apply RBAC filtering.

Required headers

• cg-username – The Optimizely CMS username.
• cg-roles – A comma-separated list of CMS roles.

When both headers are present, Optimizely Graph returns only content that the specified user or roles can access.

A content item is returned if it includes at least one of the following permissions:

• u:{USERNAME}:Read
• r:{ROLE}:Read

Example

cg-username: Tom
cg-roles: Editors,Reviewers

In this example, Optimizely Graph returns content that meets any of the following conditions:

• Includes u:Tom:Read in its RBAC list
• Includes r:Editors:Read in its RBAC list
• Includes r:Reviewers:Read in its RBAC list

Include deleted or expired content

Use the following optional headers to expand or filter the result set:

• cg-include-deleted – Returns content items where _deleted is true alongside active content.
• cg-include-hard-deleted – Returns hard-deleted content items alongside active content.
• cg-include-deleted-only – Filters results to return only deleted content. Use this header with cg-include-deleted for soft-deleted content or with cg-include-hard-deleted for hard-deleted content. For query examples, see Modified and deleted content items.
• cg-include-expired – Returns content items where StopPublish is set to a past date.

Example: HMAC request with RBAC headers

The following example shows a GraphQL query authenticated with HMAC and filtered using RBAC headers.

curl -X POST "https://cg.optimizely.com/content/v2" \
  -H "Authorization: hmac YOUR_SIGNATURE" \
  -H "cg-username: [email protected]" \
  -H "cg-roles: editor,author" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ Article { items { title } } }"}'

HMAC authentication supports both unrestricted access for system-level integrations and fine-grained access control through request headers. This flexibility lets you query content securely while aligning results with CMS permissions when required.