All posts

Product

Keys: generated in your browser, never sent

The Wytness Team
·4 min read

The least glamorous page in the dashboard might be the most important. Every claim the recorder makes — this event is yours, this data is sealed, this trail is verifiable — traces back to what happens on the Keys page. Here's the tour, including the parts that are deliberately inconvenient.

Four keys, four jobs

  • The API key answers "who may send events?" One per environment, labelled, shown in full exactly once at creation — after that, the page knows it only by its hint.
  • The signing key answers "who attested to this action?" It signs every event envelope, and it's the key your auditor's verification runs against.
  • The encryption key and optional HMAC secret answer "how does personal data stay sealed?" They power pseudonymisation — the reason PII never reaches us in the first place.

Separate keys for separate jobs isn't ceremony — it's what lets each one be rotated, scoped, and revoked without touching the others. A leaked API key is revoked without invalidating a single signature; a rotated signing key never disturbs the sealed data. Blast radii stay small because the jobs never share a key.

YOUR ENVIRONMENTYour browsertweetnacl.box.keyPair()crypto.getRandomValues()Your SDK envWYTNESS_PII_PUBKEYWYTNESS_SIGNING_KEYWytness wrapper (in your agent process)pseudonymise PII · Ed25519-sign each eventsignedWYTNESSCannot decryptno key, no derivationWhat we holdpseudonyms onlypublic-key fingerprintWytness ingestverifies signature
the ceremonyprivate halves stay with you · Wytness registers public halves only

The ceremony

Generating a key happens in your browser, on your machine. The private half is offered to you for safekeeping and is never transmitted; the public half registers against your org automatically. The page enforces the discipline structurally: it only accepts public material and first-and-last-four-character hints, so there is no field into which a private key could even be pasted. Rules that depend on people remembering them fail; this one is built into the form.

No implicit trust, anywhere

The wrapper refuses to start without a signing key configured. The ingest endpoint rejects events whose envelope doesn't verify against a registered public key — there's no "trust on first use", no grace for unregistered senders. Strict defaults here are what make the trail defensible later: every event in your record got there by proving itself at the door.

Rotation without a flag day

Real teams rotate keys — offboarding, suspected leaks, or plain good hygiene — and the page is built for it. Multiple keys can be active in the same scope at once, so you can bring a new key up before retiring the old one; each event names the key that signed it, and the platform verifies against whichever registered key matches. Signing keys can also be scoped to a single agent, with a grace window so a wrapper can be updated without dropping events. Rotate on a cadence; revoke — not rotate — the moment you believe a private key has leaked.

The distinction earns a walkthrough, because the day you need it is a bad day to learn it. Rotation is orderly: new key generated, registered, deployed, old key retired once nothing signs with it — no gap, no flag day. Revocation is the emergency brake: the key stops being accepted now, and anything still using it fails loudly — which, if the key genuinely leaked, is exactly the behaviour you want. Events signed before the revocation stay verifiable against the key that was valid when they were written; killing a key doesn't rewrite history, it fences the future.

The costs, stated up front

Two consequences are worth knowing before you rotate the sealing side: token maps encrypted under an old key still need that old key to reveal, and rotating the HMAC secret breaks pseudonym continuity — the same customer will tokenise differently across the boundary, which matters for cross-session compliance queries. Neither is a flaw; both are the unavoidable arithmetic of keys we don't hold, and the page tells you before you act rather than after. The practical takeaway: retire old sealing keys to your vault's archive, never to the shredder.

Even the key page has a tape

Every action here — a key created, rotated, revoked — lands in the Key History with who and when. Governing the recorder produces its own record, which is exactly the answer for the auditor who asks "and who controls the keys?" It's turtles all the way down, deliberately: the mechanism that makes your agents accountable is itself accountable, in the same format, on the same page.

The philosophy behind all of this is in You hold the keys. Questions about a rotation plan? Ask us.

ShareXLinkedIn

Keep reading

We set no cookies. Sign-in and preferences use essential first-party browser storage only — no tracking, advertising, or third-party analytics. Privacy Policy

Four keys, four jobs
TABLE OF CONTENTS