Skip to content

Site keys and rotation

One secret per site, kept in your server's environment. You can swap it without signing anyone out.

What the key is

You create a site key in the dashboard. It is shown once. It looks like this, with a 16 character id and a 64 character secret:

plk_<id>_<secret>

Put it in your site's environment as PREVIEWLATCH_KEY. From the secret, your server derives two separate values:

  • A cookie signing key. Used to sign and check session cookies. It never leaves your server.
  • An API token. Sent to PreviewLatch to check passwords and sessions. PreviewLatch keeps only a hash of it, so it can recognise the token without being able to use it.

The key and both derived values never appear in a response, a log line or a browser bundle. Keep the key out of anything named NEXT_PUBLIC_.

Rotating a key

PREVIEWLATCH_KEY can hold one or two keys separated by a comma. The first signs new cookies and talks to PreviewLatch. Both are accepted when checking cookies. A site can have at most two active keys.

  1. In the dashboard, create a second key for the site.
  2. Deploy with the new key first and the old one second:
    PREVIEWLATCH_KEY=plk_new...,plk_old...
  3. Retire the old key in the dashboard. It can no longer talk to PreviewLatch.
  4. Later, once cookies have been refreshed under the new key, drop the old key from the environment and deploy again.

Sessions belong to the site, not to a key, so people stay signed in through a rotation. Cookies are re-signed with the new key at their next recheck.

Removing a key from the environment is immediate

If a key leaks

  1. Create a new key in the dashboard.
  2. Deploy with only the new key. Cookies signed with the leaked key stop working at once, so people sign in again.
  3. Retire the leaked key in the dashboard, so it can no longer check passwords or sessions.

If the key is missing or wrong

The gate fails closed. If PREVIEWLATCH_KEY is missing or malformed, every request gets a 503 with a generic "not set up" screen, and the server logs one clear error. The site never opens up because of a configuration mistake. If PreviewLatch says the key is not valid (for example it was retired), sessions end and nobody can sign in until a valid key is deployed.