Rotation

Rotating means replacing the secret without replacing the integration. The API generates a new key with the same configuration and leaves the old one answering for a while, so you can swap the secret in your systems without breaking anything.

When to rotate

• When someone who had access to the key leaves the team or the supplier.
• When the key passed through somewhere you do not control: a ticket, a chat, a log, a screenshot, a borrowed machine.
• When you change server, provider or deployment tool.
• On a regular schedule, if you want that routine.

There is no mandatory interval here, and the API enforces none. If you want a routine that is easy to keep, pick an expiration when creating the key (30 days, 90 days or 1 year) and treat that date as the reminder to rotate.

If you suspect the key leaked, the answer is not an overlap: it is stopping the old key right away. See Key best practices.

What rotation copies

Copied from the old key: the name, the permissions, the represented member, the IP list and the expiration date.

Not copied: the secret, which is new; the usage log; the idempotency keys.

The usage log stays with the key that made each call. The new key starts with an empty list under View usage, and the old one’s history stays on the old one.

The overlap

In the panel: key menu, Rotate. The form asks for your password, and only the OWNER and ADMIN can rotate. You choose how long the old key keeps working.

Choice	What happens to the old key
Stop now	Revoked in the same action. The next call with it gets a 401
1 hour	Keeps answering for 1 hour and stops on its own at the end
24 hours	Keeps answering for 24 hours and stops on its own at the end

During the overlap both keys answer, and the old one shows as Rotating in the panel. You do not have to wait for the window to end: revoke the old one as soon as you confirm the swap.

Webhook endpoints subscribed with the old key follow the rotation: with 1 hour or 24 hours, they move to the new key in the same action and keep receiving; with Stop now, they are paused, and the owner and admins get the list by email to review, because whoever got the key may have registered an endpoint. In the dashboard, a paused endpoint shows the reason “Paused for security” (in the API, disabled_reason: "emergency_key_rotation"), and turning it back on asks for your password. See Webhooks.

Step by step

1. Rotate, choosing the overlap window.
2. Copy the new key. It is also shown once.
3. Swap the secret in your systems.
4. Confirm with a call to GET /public/v1/me using the new key and compare the key.prefix in the response with the prefix the panel shows on the new key. That is how you know your system is using the new key and not the old one left in some cache.
5. Revoke the old one.

The traps

The new key inherits the expiration date of the old one. Rotating a key that expires next week gives you a key that also expires next week. Rotation swaps the secret, it does not renew the term. To gain term, create a new key.

The new key takes a slot in the quota while the old one is alive. The plan’s key quota counts every key that still authenticates, and the old one in overlap still authenticates. Rotation itself is not blocked by the quota, but creating one more key is, until the old one is revoked or expires. If the company is already at the cap, choose Stop now or revoke the old key as soon as you swap.

Idempotency does not cross a rotation. An idempotency key is scoped to an API key. The same Idempotency-Key sent with the new key is a new request, not a replay of the previous one: if the first one had already created a record, the second creates another. Finish whatever is in flight with the old key, or wait for the response before swapping the secret. See Idempotency.

A key that was already rotated cannot be rotated again. Whoever rotates twice rotates the new key. A revoked or expired key cannot be rotated either: there the way out is to create a new key.

An expiration date earlier than the end of the overlap wins over the overlap. If the old key already expired in 6 hours and you chose 24 hours, it stops in 6 hours.

A key of a suspended member cannot be rotated. Reactivate the member or create a key for another member.

Whoever is left behind

After the old key stops, a call made with it gets the same 401 of an invalid key, without saying the reason was the rotation.

The panel is what tells you: the attempt shows up under View usage of the old key, with the address it came from and the time. That is how you find the system still holding the old secret.

The OWNER and ADMIN get an email on every rotation and every revocation.

Next step

• Key best practices: what to do if the key leaked.
• Allowed IPs: the new key is born with the same list.
• Idempotency: why a replay does not cross a rotation.