HideGuardDocumentation

Reference · Trust and verification

GET /api/v1/signing-key

Fetching the public key, and how rotation works.

Fetching the public key used to verify replies.

GET /api/v1/signing-key?siteKey=pk_live_...

Why there is a `siteKey` parameter#

The signing key is per workspace. The answer differs by site, so the question has to name one.

Reply#

{
  "trustedKeys": [
    { "kid": "hg_<ws>_<yyyymm>", "publicKey": "-----BEGIN PUBLIC KEY-----\n..." }
  ]
}

trustedKeys is an array, not a key. The reason is rotation, below.

This is bootstrap, not a verification step#

Do not call this on every verification. Fetch once, cache, and refetch only on a kid you do not know. A verification that depends on a network call is a verification that breaks when the network does.

Rotation#

A kid has the form hg_<workspace>_<yyyymm>.

When a workspace gets its first key of its own, the collector-wide key keeps being published for four cache lifetimes. That is what makes the switch need no restart and leave no window in which a reply cannot be verified.

The signer and the published set always change together, so the page and the signature can never disagree.

How the private key is stored#

The private half is sealed before it is stored, so a database dump cannot sign.