Content Recommendations Authentication and Tokens

Every Content Recommendations API is headless and authenticates with a Headless API token passed in the X-API-Key request header:

X-API-Key: <your-token>

Headless API tokens are separate from Developer Center tokens. This page is the single reference for which token each surface needs, how to provision them, and how to handle them safely. Other Content Recommendations guides link here instead of repeating this material.

One token per API surface

Provision a separate token for each API you use, each assigned to its own key collection:

Key collection	Authenticates	Used by	Where it may live
recommend	`GET /recommend/v1/*` (read-only)	Your front-end, the recommendations block, email senders	Browser-safe. It can only read recommendations, so it may ship in page JavaScript.
collector	`POST /collector/v1/` (events and* content writes)	Your CMS webhook, the IFX bundle, CDP/server-side forwarders, bulk loads	Server-side only. It writes to your catalog and training data — it must never appear in a browser bundle.
collect-web (browser events)	`POST /collect-web/v1/events/batch`	The Compass Web SDK	Browser-safe. It can post browser events but cannot reach the content catalog.

Why separate key collections

Assigning each token to its own key collection means a token exposed in one context cannot be used against another API. The separation is what makes the browser-safe keys safe: the recommend and collect-web keys are public by design (anyone can read them out of your page source), and their collections limit the blast radius of that exposure to read-only recommendations or event submission. The collector key has no such containment — treat it like any other server-side secret.

Provisioning

Tokens are provisioned through the Delivery API. The full flow — generating a bootstrap Developer Center token, creating Headless API tokens via POST /v1/access/keys, and assigning them to key collections — is documented in Provisioning tokens through Delivery API.

Limits to plan around:

Tokens are limited to 30 per environment (Sandbox and Production).
Tokens are created one at a time.
Deletion via DELETE /v1/access/keys/{key_id} also operates on a single token at a time.

Handling rules

Never commit tokens to source control. Store them in your secrets manager and inject them at deploy time (for the IFX bundle, as integration secrets in Developer Center).
Rotate tokens on whatever cadence your security policy requires.
Remove tokens that are no longer in use. The 30-token-per-environment limit is easy to hit if old tokens linger.
Keep one token per consumer where practical. A dedicated token per integration (block, IFX bundle, forwarder, bulk-load job) makes rotation and revocation surgical instead of site-wide.

Verifying a token

Confirm a recommend key is accepted:

curl -i -H "X-API-Key: <recommend-key>" \
  "https://<org>-config-prod.api.arc-cdn.net/recommend/v1/recommendations?site_id=<site_id>&user_id=test-user"

200 — the key works (an empty recommendations array on a cold catalog is still success).
401 / 403 — the key is missing, unknown, or not assigned to the right key collection. Re-check the assignment step in the provisioning guide.

The same check applies to the collector key against POST /collector/v1/events, which returns 202 Accepted when the key and payload are valid.