# Rotation

> There is no rotation operation: a key is replaced by creating a new one, then revoking the old one. The zero-downtime procedure, and what survives the change.

Noryo Merchant API offers no rotation operation: no button and no route turns one key into another. Replacing a key takes two visible actions, each of which leaves its own trace: **create a new key**, then **revoke the old one**. Several active keys can coexist in a workspace, which lets you change keys without downtime.

## When to replace a key

- The secret is lost: it is never recoverable.
- The secret has leaked, or you suspect it has: see also [Keeping secrets safe](https://developer.noryo.app/en-GB/merchant/authentication/secret-security).
- A person or supplier who knew the secret must no longer have access.
- You want different scopes: scopes are chosen at creation.

## 1. Create the new key

On the [API keys](https://platform.noryo.app/keys) page of Platform, create a key in the same workspace and the same environment, with the required scopes. Copy the secret: it is shown only once.

Platform issues Sandbox keys: this procedure applies to them as written.

## 2. Deploy the new key

Replace the value in your secrets manager or environment variable, then redeploy. During the transition, both keys work.

## 3. Check that the old key is no longer used

The key list shows the last-use date of each key. Wait until the new key is being used and the old one no longer is. The [Usage](https://platform.noryo.app/usage) page also lists recent settled calls, with their `request_id`.

## 4. Revoke the old key

Revoke it on the same page. From the next request, it is refused with `401 invalid_api_key`. Revocation cannot be undone from Platform. See [Revocation](https://developer.noryo.app/en-GB/merchant/authentication/revocation).

## What survives the change of key

Results, idempotency and deduplication belong to the workspace and the environment, not to the key. Changing keys within the same workspace therefore breaks nothing:

| Item | After the change of key |
|---|---|
| Results | `enrichment_id` values created with the old key remain readable with the new one |
| `Idempotency-Key` | A retry sent with the new key, the same `Idempotency-Key` and the same body replays the memorised response, within the 24-hour window |
| `external_transaction_id` | Deduplication carries on: a transaction already settled is not billed a second time |
| Rate-limit bucket | The new key has its own bucket, full to begin with |
| Scopes | Those chosen when the new key was created |

> **Note** A key created in another workspace sees neither the results, nor the idempotency keys, nor the deduplication of the old one. Always replace a key with a key of the same workspace.

## What does not exist

There is no automatic rotation, no scheduled expiry and no grace period after revocation: a key remains valid until you revoke it, and stops being valid as soon as it is revoked.

---

Canonical page: https://developer.noryo.app/en-GB/merchant/authentication/rotation