Customer Keys and Grants

A grant is the authority a customer gives your firm to act inside their estate. That authority is the customer's own API key, held by the firm. Everything the portal does inside an estate, it does as that account.

Holding the key

You supply the key once, in the custody panel on the customer. The portal resolves which account it belongs to on the server, stores it there, and does not show it again.

The key never reaches your browser. Every control-plane call the portal makes on a customer's behalf runs server-side, so the browser sees results and never credentials. That also means a colleague working the book cannot read out a customer's key, whatever role they hold.

What the firm sees

Acting as the account means seeing exactly what the account sees. There is no wider view assembled around the customer, and no narrower one: the key is the whole of the authority, and the portal inherits the scopes that key carries. A verb the key has no scope for fails the same way it would fail for the customer, and the response verbs name the scope each one needs.

When there is no grant

Without a grant, the portal reads nothing from that estate and says so on the screen that needed it. It does not render a zero, because a zero reads as a quiet customer, and an unread estate is not a quiet one. The same rule holds across the book: an ungranted estate is reported as ungranted in the queue, in a hunt and in a prove answer.

Ending access

Access ends when the customer rotates the key in their own account. The replaced key stops working, and the firm's stored copy stops with it. Nothing else has to be unwound, and nothing at the firm has to be trusted to do it: the customer holds the only thing that matters.

Supplying a replacement key restores the grant, and the estate reads again from the next call onward.

The key itself

A Whisper key looks like whisper_live_... and travels in the X-API-Key header on every call to the control plane. It is minted in the account it belongs to, at https://console.whisper.security, which means the customer mints and rotates their own. Keys and scopes covers the header and what a key is allowed to do.

One grant, from start to finish

A customer's key goes into the custody panel during onboarding. The portal then lists their endpoints, pushes a resolver rule and opens a case, all as that account, and each of those actions lands in the estate's own record where the customer can read it. The customer later rotates the key: the next call fails, the estate reads as ungranted, and every screen that needed it says so until a new key is supplied.