Secure Optimizely Graph API Access with HMAC Authentication

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. Percent-encode the value when it contains non-ASCII characters.
cg-roles – A comma-separated list of CMS roles. Percent-encode a role when it contains non-ASCII characters.

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

Send non-ASCII usernames and roles

HTTP header values carry only ASCII characters. A username or role that contains a character such as å, ä, or ö does not fit this restriction. Percent-encode the value as described in RFC 3986. Optimizely Graph decodes the header before it evaluates access.

Optimizely Graph decodes the two headers as follows:

cg-username – Optimizely Graph decodes the entire header value.
cg-roles – Optimizely Graph splits the value on commas, then decodes each role separately.

The split happens before decoding, so a comma in the header always separates roles. To include a comma in a role name, encode it as %2C.

The following example sends the username fö[email protected] and the roles Redaktör and Team Alpha:

cg-username: f%C3%B6rnamn%40optimizely.com
cg-roles: Redakt%C3%B6r,Team%20Alpha

Keep the following behavior in mind:

Plain ASCII values need no encoding, so existing headers keep working unchanged.
Optimizely Graph trims leading and trailing whitespace from each decoded value, and it ignores empty entries in cg-roles.
Optimizely Graph passes a malformed value through unchanged. A stray % sign does not cause an error.

Encode the header values in the client that calls Optimizely Graph. A client that puts non-ASCII characters straight into a header fails before it sends the request. The HTTP library rejects the value first.

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.