Skip to content

Provision and Manage Compass API Keys

Last updatedView as Markdown

This guide walks you through getting the Headless API tokens your Arc XP Compass integration needs, confirming they work, and keeping them safe over their lifetime.

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

X-API-Key: <your-token>

Headless API tokens are separate from Arc XP Developer Center tokens. For which key collection authenticates which API, and where each key may live, see One token per API surface.

1. Decide which tokens you need

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

  • Compass Web SDK: one token, assigned to both the collect-web and experiences collections. The SDK sends it on event posts and on the SDK-rendered Experiences’ reads. An SDK-only rollout needs only this one browser token.
  • Recommendations API called from your own code (your own UI, the recommendations block, an email sender, or a server-side caller): a token in the experiences collection.
  • Server-side content ingestion or event forwarding (your CMS webhook, a bulk load, a CDP or server-side forwarder): a token in the collector collection.

2. Provision each token

Tokens are provisioned through the Delivery API. The full flow (generating a bootstrap Developer Center token, creating Headless API tokens with 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 with DELETE /v1/access/keys/{key_id} also operates on a single token at a time.

3. Verify the token

Confirm an experiences key is accepted:

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

The status code you get back depends on both the key and your tenant lifecycle status together with whether your catalog has content yet. A valid key does not by itself guarantee a 200:

  • 401 — the key is missing, unknown, or not assigned to the right key collection. Decided before any catalog lookup.
  • 403 (Cache-Control: no-store), body {"detail":"Tenant is not active"} — the key is valid, but the tenant is not servable (onboarding with no content yet, or suspended/pending/deleted).
  • 200 — the key is accepted. This includes an all-0.0 recency preview and an empty recommendations: [], both of which are success. See Cold-start response states for the full breakdown.

So an empty array or an all-0.0 preview still means the key works; only 401 and 403 indicate a problem to fix. The same check applies to the collector key against POST /collector/v1/events, which returns 202 Accepted when the key and payload are valid.

4. Store and use tokens safely

  • Never commit tokens to source control. Store them in your secrets manager and inject them at deploy time (for an IFX integration you build yourself, as integration secrets in Developer Center).
  • Keep one token per consumer where practical. A dedicated token per integration (block, IFX integration, forwarder, bulk-load job) makes rotation and revocation surgical instead of site-wide.
  • Rotate tokens on whatever cadence your security policy requires.

5. Remove tokens you no longer use

The 30-token-per-environment limit is easy to hit if old tokens linger. Remove a token that is no longer in use with DELETE /v1/access/keys/{key_id}, one token at a time. See Provisioning tokens through Delivery API.

Migrate from /recommend/v1

The older /recommend/v1 base path and its recommend key collection are deprecated and no longer provisioned for new organizations. If your integration calls /recommend/v1, move it to /experiences/recommend/v1. The endpoints, parameters, and responses are the same; only the path changes.

  1. Assign your read key to the experiences collection.
  2. Confirm your site’s origin is allowed there.
  3. Change the base path in your integration from /recommend/v1 to /experiences/recommend/v1.
  4. Verify the token against the new path.

See also