# Provision and Manage Compass API Keys

Source: https://dev.arcxp.com/content-recommendations/content-recommendations-api-keys/

Provision, verify, rotate, and remove the Headless API tokens that Arc XP Compass requires.

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](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#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.

> **Caution:**
> 
> Never use the **collector** key in client-side code, in the recommendations block, or in the Compass Web SDK’s `init()`. It writes to your catalog and training data and must stay server-side. Only the **experiences** and **collect-web** keys belong in the browser.

## 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](https://dev.arcxp.com/platform-tools/developer-docs/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

```bash
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](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#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](https://dev.arcxp.com/platform-tools/developer-docs/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](#3-verify-the-token) against the new path.

## See also

- [Authentication and tokens](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#authentication-and-tokens) — the key-collection model and which surface each token authenticates.
- [Compass Prerequisites & Enablement](https://dev.arcxp.com/content-recommendations/content-recommendations-prerequisites-enablement/) — what must be in place before you integrate.
- [Troubleshoot Compass Recommendations](https://dev.arcxp.com/content-recommendations/content-recommendations-troubleshooting/) — diagnosing `401`, `403`, and empty responses.
