Keys / Unkey

UNKEY_ROOT_KEY

The root key your services, CI and agents call the Unkey API and CLI with. It belongs to one workspace.

Starts with
unkey_
Expires
never, unless you set an expiry through the API
API
create, update, reroll and delete, with a root key

Get it

Create one on app.unkey.com. The steps aren't recorded yet.

Set it

UNKEY_ROOT_KEY=unkey_...

The TypeScript SDK @unkey/api reads it when you don't pass rootKey, and the Unkey CLI reads it when you don't pass --root-key. Or keep it out of .env with keypin: keypin run -- npm run dev

Replace it

  1. On the workspace's Root Keys page, choose Rotate root key from the key's menu. The new key keeps the name, permissions, IP allowlist and expiry.
  2. Pick a grace period, up to 24 hours. The old key stops when it ends, or at its own expiry if that comes sooner.
  3. Deploy the new key everywhere that reads UNKEY_ROOT_KEY before the old one stops.

Set rotate_every on the key in keypin.toml and a rotated date on its vault item, and keypin status shows when it's due.

Sources, checked 2026-11-16