Heretic API Keys: Collector Setup and Explain Endpoint

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

Sign in at heretic.quest/dashboard.
Navigate to heretic.quest/dashboard/keys.
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.

import { Collector } from '@heretic-hq/collector';

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

const sessionId = await collector.collect();

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.

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.

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

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.

headers: {
  'Authorization': `Bearer ${process.env.HERETIC_API_KEY}`,
}

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.

Rotate a Key

To rotate a key, go to 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.

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.

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 for what those records contain and what happens when you delete them.

Get Started

Core Concepts

Integration

Dashboard

Reference

Heretic API Keys: Collector Setup and Explain Endpoint

Get Your API Key

Use Your Key

Collector Initialisation

Explain Endpoint Calls

Best Practices

Rotate a Key

Deleting a Site

​Get Your API Key

​Use Your Key

​Collector Initialisation

​Explain Endpoint Calls

​Best Practices

​Rotate a Key

​Deleting a Site

Get Your API Key

Use Your Key

Collector Initialisation

Explain Endpoint Calls

Best Practices

Rotate a Key

Deleting a Site