Rotation with two keys

Replace a key without downtime — register a second key, switch your software, then revoke the first.

An app holds at most 2 active keys. That is all rotation needs; there is no "retired" state and no grace period.

The three steps#

Register a second key on the same app (Integration › Apps and keys › Register key). Both keys now verify.
Switch your software to the new key id and private key. Check with GET /ping.
Revoke the first key (Revoke on its row). Requests signed with it are refused immediately with 401 key_invalid. This can't be undone.

When the key you revoke is the app's only active key, requests stop until you register a new one — the Partner Portal says so in the confirm dialog.

If the app already has two active keys, Register key is disabled with "This app has 2 active keys. Revoke one first." (key_limit_reached).

Keys live 365 days from registration. Thirty days before a key expires we warn you three ways:

a warning on the Partner Portal overview: "Key {key id} expires on {date}. Register a new key, switch your software to it, then revoke this one.";
the webhook key.expiring, with details: { key_id, expires_at } (see Events and deliveries);
an email to your partner admins.

Code	HTTP	Cause	Fix
`key_invalid`	401	unknown key id, or the key was revoked	use an active key; register a new one if needed
`key_expired`	401	the key is past its 365 days	register a new key and switch to it

Last updated 12 Oct 2026