Authentication and Endpoint

Endpoint

All operations are served from a single endpoint:

POST /graphql/v1
Alias (deprecated): POST /graphql

Example request:


POST /graphql/v1

Content-Type: application/json

X-Access-Key: your-api-key


{

  "query": "query Sites { sites { id name domain timezone status } }"

}

API Key Authentication

Provide an API key on every request:

Preferred: X-Access-Key request header
Fallback: ?access_key=your-api-key query parameter

Header usage is recommended for logs, proxies, and client consistency.

Create an API Token

Go to portal.heatmap.com.
Click **Settings** (bottom left).
Select **Access Keys**.
Create an access key.
Copy the key immediately. It is shown only once, and we do not store the raw key.

Testing

Open https://insights-api.heatmapcore.com/graphql/v1 in your browser.
Add your token to the X-Access-Key request header.
Press Shift+Ctrl+R to refresh and load the schema.
Have fun testing.

Bypass Mode (Non-Production)

When API_KEY_BYPASS_ENABLED=true, authentication is bypassed and viewer scope is synthetic full access.

Use this mode only for local development and controlled debugging.