Rotate Keys¶

What this is: changing the system's secret keys — like changing the locks. There are two keys to rotate: the signing key (how the system proves messages are genuine) and the group key (the shared key that scrambles message contents). When you'd do it: on a routine schedule, or immediately if you suspect a key has leaked. How long it takes: about two minutes.

Who can do this: an Admin. These screens only show up if your own login has the Admin role. A normal Operator login won't see them — if the menu below isn't there, ask an admin to do this.

You'll do everything on a single page — the Key Management page — no command line needed.

One reassuring thing to know before you start: the system keeps the previous group key around briefly after you rotate, so messages already in flight still arrive safely. People don't get cut off mid-conversation. You're rolling forwards, not back — there's no "un-rotate", and you won't need one.

The shape of it¶

flowchart LR
    A["Open the<br/>Key Management page"] --> B["Rotate<br/>signing key"]
    B --> C["Rotate<br/>group key"]
    C --> D["Everyone picks up<br/>the new keys automatically"]

Two button clicks on one page, and the system takes care of the rest.

Before you start¶

You're signed in to the Directory site as an admin.
You know why you're rotating (scheduled cadence, or suspected leak). If it's a suspected leak of the group key, plan to revoke any affected principals afterwards — see revoking a principal.

Steps¶

Open the Key Management page. In the admin site, navigate to Key Management (the URL is /admin/keys). You'll see two cards side-by-side: Directory Signing Key on the left and Group Key on the right.
Note the current fingerprint and epoch. Before you click anything, glance at the Current fingerprint on the signing key card and the Current epoch on the group key card. It's useful to know the before-state if you're auditing later.
Rotate the signing key. On the Directory Signing Key card, click Rotate signing key. A confirm dialog will ask:

Rotate the Directory signing key? New tokens will be signed with a fresh key. The current key stays served until its tokens expire.

Click OK. The page reloads and shows a green success message: "Signing key rotated. New fingerprint: …" — with the new fingerprint value.

Rotate the group key. On the Group Key card, click Rotate group key. A confirm dialog will ask:

Rotate the group key? A new epoch is minted and the oldest epoch is retired from /api/group-key.

Click OK. The page reloads and shows a green success message: "Group key rotated. New epoch: …" — with the new epoch number.

You're done. Devices pick up the new group key automatically on their next background poll — nothing else for you to do.

How to know it worked¶

After rotating the signing key, the Current fingerprint on the page shows a new value, and you saw the green "Signing key rotated. New fingerprint: …" banner.
After rotating the group key, the Current epoch on the page has incremented by one, and you saw the green "Group key rotated. New epoch: …" banner.
If you didn't see either green banner, the rotation didn't complete — try again.

If something goes wrong¶

The page showed an error instead of a success message. Reload the Key Management page and check whether the fingerprint or epoch changed. If they didn't, try the rotation again. If the error persists, escalate to a developer.
You rotated the signing key but not the group key, then left the page. No problem — come back and rotate the group key. The two rotations are independent.
You're worried devices haven't picked up the new group key. Devices poll automatically in the background. If an operator reports connection trouble shortly after a rotation, reassure them it should resolve within a few minutes as their device refreshes. If trouble persists, see the architecture glossary for details on epoch retirement.