Create account
Sign inCreate account
Documentation menuKey rotation

Key rotation

Rotate site secret keys without downtime, and how BlockAlt rotates its own signing keys without breaking your pages.

On this page

Site secret keys #

A site can have several active secret keys, so you can rotate without downtime:

  1. Create a new key in the console (it is shown once).
  2. Deploy it to your backend, for example as BLOCKALT_SECRET.
  3. Verify a real token with the new key and check the decision log.
  4. Revoke the old key. Revocation applies to the next verification that uses it.

Configuration signing keys #

The script trusts only site configuration signed by a key you pinned in configPublicKeys. GET /v1/keys lists every key to pin: the current Ed25519 and P-256 keys (browsers without Ed25519 use P-256), then the standby keys of the next rotation, kept offline until needed.

Shell
curl -sS https://blockalt.click/v1/keys
  • Pin all of them. When we rotate, the standby keys become current and new standby keys are published; pages that pinned the full list keep working without any change.
  • After a rotation, update your list at your next deploy. Rotations are announced on the changelog in advance, except after a compromise, when the old key is removed at once.
  • A page whose pinned keys are all retired stops getting tokens: the script rejects with invalid_config.

Token and challenge keys #

Challenges and tokens are authenticated with HMAC keys that never leave BlockAlt's servers, with a key id in every token. We rotate them on our side; nothing changes in your pages or your backend.

Public site keys #

The public site key is not a secret. It identifies the site and only works from the site's verified origins.

Something unclear or missing on this page? Write to support@blockalt.click.