API keys & cluster scoping

How StackRadar API keys work: cluster-scoped vs org-scoped keys, why SBOM uploads require a cluster-scoped key, and how to create and rotate keys safely.

Two kinds of keys

Scope	Attached to	Used for
Cluster-scoped	Exactly one cluster in one organization	The scanner agent: SBOM uploads and heartbeats
Org-scoped	The whole organization	General API access that isn't tied to a single cluster

Keys are sent in the X-API-Key header on every request to api.stackradar.io.

Why SBOM uploads require a cluster-scoped key

SBOM uploads are rejected for org-scoped keys, deliberately. A cluster-scoped key gives every upload an unambiguous origin:

Attribution — every SBOM, workload, and vulnerability in the dashboard traces to the cluster that reported it. With a shared org-wide key, fleet views ("which clusters run the vulnerable image?") would be guesswork.
Blast radius — a key that leaks from one cluster's CI values file or Secret compromises that cluster's reporting identity, not your whole organization's.
Clean revocation — decommission a cluster by deleting its key. Nothing else changes.
Health tracking — heartbeats update the key's cluster (last-seen time and scanner version), which is how the dashboard knows a specific cluster went quiet.

Creating a key

In the dashboard, create (or open) the cluster you're connecting.
Generate its API key and copy the cluster ID alongside it.
Pass both to the Helm chart — see the quick start.

Treat the key like any workload credential: don't commit it to git. Pass it at install time from your secret manager or CI secret store rather than hardcoding it in a values file.

Rotating a key

Rotation is a Helm upgrade — no reinstall:

bash

# 1. Generate a new key for the cluster in the dashboard
# 2. Roll the scanner onto it
helm upgrade stackradar-scanner \
    oci://ghcr.io/lockdep/charts/stackradar-scanner \
    --namespace stackradar --reuse-values \
    --set stackradar.apiKey=$NEW_STACKRADAR_API_KEY
# 3. Revoke the old key in the dashboard

After rotating, confirm the cluster still shows as connected, then revoke the old key. A revoked key fails immediately with 401 Unauthorized.

Auth errors you might see

Response	Meaning
`401 Unauthorized`	Missing, mistyped, or revoked key in `X-API-Key`
`403 Forbidden` on SBOM upload	The key is org-scoped; uploads need a cluster-scoped key

More failure modes (cluster never connects, SBOMs missing) are covered in Troubleshooting.