API keys & cluster scoping

How StackRadar API keys work: one cluster-scoped key per cluster, why every scanner request requires one, and how to get and rotate keys safely.

One key per cluster

API keys are cluster-scoped: each key belongs to exactly one cluster in one organization, and each cluster has at most one active key. The key is generated when you create the cluster in the dashboard and shown once — it is the credential the scanner agent uses for everything it sends: heartbeats, workload inventory, SBOM checks, and SBOM uploads.

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

Why every scanner request requires a cluster-scoped key

The entire scanner ingest surface — heartbeats, inventory, SBOM checks, and uploads — rejects any key that isn't bound to a single cluster, deliberately. A cluster-scoped key gives every report 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.
Isolation — everything derived from an upload (the image, its SBOM, its findings) belongs to the key's cluster and is never shared across clusters, so one cluster's reports can't poison another's.
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 revoking its key. Nothing else changes.
Health tracking — heartbeats update the key's cluster (last-seen time, scanner version, and Kubernetes version), which is how the dashboard knows a specific cluster went quiet.

Getting a key

In the dashboard, create the cluster you're connecting. Its API key is generated as part of the flow and shown once — copy it together with the cluster ID.
Pass both to the Helm chart — see the quick start.
Lost a key? You can't recover it, but an admin or owner can rotate it at any time from the cluster's Settings tab, or from Organization Settings → API Keys.

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

Rotate from the cluster's Settings tab (or Organization Settings → API Keys). Rotating immediately revokes the existing key — the running scanner fails authentication until you roll it onto the new one, so have the Helm upgrade ready:

bash

# 1. Rotate the key in the dashboard (the old key stops working immediately)
# 2. Roll the scanner onto the new key
helm upgrade stackradar-scanner \
    oci://ghcr.io/lockdep/charts/stackradar-scanner \
    --namespace stackradar --reuse-values \
    --version <installed-version> \
    --set stackradar.apiKey=$NEW_STACKRADAR_API_KEY

Pin --version to the chart version you are already running (helm list -n stackradar shows it) — without it, Helm pulls the latest chart and the rotation becomes a scanner upgrade too.

After upgrading, confirm the cluster shows as connected again. A revoked key fails with 401 Unauthorized; nothing already uploaded is affected.

Auth errors you might see

Response	Meaning
`401 Unauthorized`	Missing, mistyped, or revoked key in `X-API-Key` — an expired key fails the same way
`403 Forbidden`	The key isn't cluster-scoped, or the `STACKRADAR_CLUSTER_ID` the scanner was installed with (the chart's `stackradar.clusterId` value) doesn't match the cluster this key belongs to. Only the heartbeat compares the two — the other endpoints derive the cluster from the key alone — but the heartbeat is the first thing the scanner sends, so a mismatch surfaces immediately

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