Provision and Manage Compass API Keys
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-webandexperiencescollections. 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
experiencescollection. - Server-side content ingestion or event forwarding (your CMS webhook, a
bulk load, a CDP or server-side forwarder): a token in the
collectorcollection.
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:
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.0recency preview and an emptyrecommendations: [], 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.
- Assign your read key to the experiences collection.
- Confirm your site’s origin is allowed there.
- Change the base path in your integration from
/recommend/v1to/experiences/recommend/v1. - Verify the token against the new path.
See also
- Authentication and tokens — the key-collection model and which surface each token authenticates.
- Compass Prerequisites & Enablement — what must be in place before you integrate.
- Troubleshoot Compass Recommendations — diagnosing
401,403, and empty responses.