> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heretic.quest/llms.txt
> Use this file to discover all available pages before exploring further.

# Heretic API Keys: Collector Setup and Explain Endpoint

> Create and manage per-site API keys from the Heretic dashboard. Your API key authenticates collector initialization and explain endpoint calls.

Every site you register in Heretic gets its own API key, scoped to that domain alone. The key plays two roles: it authenticates the collector when it initialises in the visitor's browser, and it authenticates your server-side calls to the explain endpoint. Keep the two uses in mind — one is intentionally client-side, the other must stay server-side.

## Get Your API Key

1. Sign in at [heretic.quest/dashboard](https://heretic.quest/dashboard).
2. Navigate to [heretic.quest/dashboard/keys](https://heretic.quest/dashboard/keys).
3. Locate the site you want to configure, then copy the key shown next to it.

If you have not created a site yet, add one from the same page. Each site entry maps to one domain and produces one API key.

## Use Your Key

### Collector Initialisation

Pass your key as the `apiKey` option when you create a `Collector` instance. The collector is a client-side library — the key is intentionally visible in your front-end bundle for this purpose.

```ts theme={null}
import { Collector } from '@heretic-hq/collector';

const collector = new Collector({
  apiKey: 'hrtc_live_xxxxxxxxxxxxxxxxxxxx',
});

const sessionId = await collector.collect();
```

<Note>
  The collector `apiKey` is client-side by design. It identifies your site to Heretic's edge so measurements are attributed correctly. It only authorises the collector to submit measurements — it does not grant access to verdict results, which require a server-side explain call.
</Note>

### Explain Endpoint Calls

Your backend exchanges a session ID for a full verdict by calling the explain endpoint. Pass your API key as a `Bearer` token in the `Authorization` header.

```ts theme={null}
const response = await fetch('https://api.heretic.quest/v1/explain', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hrtc_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ session: sessionId }),
});

const verdict = await response.json();
```

## Best Practices

<AccordionGroup>
  <Accordion title="Store your explain-endpoint key in environment variables">
    The key you use in server-side explain calls must never appear in client-side code or be committed to version control. Inject it at runtime via an environment variable — for example `HERETIC_API_KEY` — and read it in your backend handler.

    ```ts theme={null}
    headers: {
      'Authorization': `Bearer ${process.env.HERETIC_API_KEY}`,
    }
    ```
  </Accordion>

  <Accordion title="Keep client and server uses separate">
    Your `apiKey` in the collector is expected to be public. Your `Authorization` header key in explain calls is a server secret. Do not reuse the same variable name or configuration path for both — keep them explicitly separated so you do not accidentally expose the server key in a bundle.
  </Accordion>
</AccordionGroup>

## Rotate a Key

To rotate a key, go to [heretic.quest/dashboard/keys](https://heretic.quest/dashboard/keys), delete the existing key for that site, and create a new one. The old key stops working immediately upon deletion — any in-flight requests using it will receive an authentication error. Update your collector build and your server environment variable before rotating in production.

<Warning>
  Rotating a key requires you to redeploy the collector with the new `apiKey` value. Plan rotations during low-traffic periods to avoid a gap in coverage.
</Warning>

## Deleting a Site

Deleting a site from the keys page removes its API key and gives you the option to delete its stored verdict records from the dashboard at the same time. See [Data Retention](/dashboard/data-retention) for what those records contain and what happens when you delete them.


## Related topics

- [Heretic Dashboard: Manage Sites, Keys, and Verdicts](/dashboard/overview.md)
- [Read and Interpret Heretic Explain Endpoint Responses](/integration/reading-verdicts.md)
- [Heretic Quick Start: Collect Sessions and Read Verdicts](/quickstart.md)
- [GET /e Explain Endpoint: Full Request and Response Reference](/api/explain-endpoint.md)
- [Heretic API: Base URL, Auth, and Error Codes Guide](/api/overview.md)