Key and credential rotation
Your node has several kinds of secrets, and they don't all rotate the same way. This page covers what you can rotate, how, and — critically — what you can never rotate because it's the money itself.
What can be rotated
| Credential | What it's for | Can rotate? |
|---|---|---|
| Admin password | Your login to the node's admin UI | Yes |
| Admin TOTP factor | Second factor for admin login + fresh-code gates on money actions | Yes (re-enroll) |
| Site key | Lets your storefront backend create checkout sessions | Yes |
| Reporting key | Lets your node push read-only payment metadata to the ZuPayments dashboard | Yes |
| Action key | Lets your browser drive the node directly from the ZuPayments dashboard | Yes |
| Wallet private keys | The actual Zucoins spend keys, treasury and sub-wallet | No — see below |
Admin TOTP re-enrollment
If you're setting up a new authenticator (new phone, lost the old one while still logged in somewhere), re-enrollment mints a brand-new secret and supersedes the old one — the old code stops working once the new factor is confirmed. This requires re-entering your current password before a new secret is issued, so someone with just a stolen session cookie can't silently swap your second factor out from under you.
There is no email-based recovery for TOTP. If you're fully locked out (lost both the authenticator and any active session), the only path back in is a new admin invite from another operator on the account, or — for a single-operator node — a fresh admin bootstrap, which by design requires redeploying the node (proof you control the underlying infrastructure). Keep a second admin account or your recovery codes somewhere safe.
API key rotation (site / reporting / action)
Each of your three API keys can be rotated independently from the admin dashboard's API Keys screen:
- Choose the key to rotate and confirm with a fresh TOTP code.
- The node issues a brand-new key (shown once — copy it immediately) and keeps the old key valid for a short grace window (about 10 minutes) before revoking it. This overlap exists so you can swap the key into your storefront config, the ZuPayments dashboard vault, or wherever it's configured, without a hard outage mid-rotation.
- After the grace window, the old key stops authenticating. Update every place the old key was configured before the window closes.
For the reporting and action key kinds specifically, your node only ever considers one instance of each "live" at a time — you rotate to replace, you don't accumulate several active reporting keys. The site key has no such limit; you can run several storefronts, each with its own site key.
If you're rotating the action key specifically because you use the ZuPayments hosted dashboard: after rotating on the node, you'll need to re-enter the new action key into the credential vault on the dashboard side (same flow as a vault passphrase change) — the old key stops working immediately node-side, so any other device using it will be locked out until it's updated with the new key.
Reference:
| Endpoint | Notes |
|---|---|
GET /admin/v1/api-keys |
List key metadata (id, type, prefix, timestamps) — never the secret itself. |
POST /admin/v1/api-keys |
Issue a new key of a given type; secret returned once. |
POST /admin/v1/api-keys/:id/rotate |
Issue a same-kind replacement; old key grace-revoked; new secret returned once. |
DELETE /admin/v1/api-keys/:id |
Revoke immediately, no grace window. |
Why wallet private keys are never rotated
This is the one that surprises people coming from typical API-key hygiene, so it's worth being explicit: there is no "rotate this wallet's key" action, and there never will be, because the key isn't a credential — it's the address the funds live at.
A Zucoins wallet's address is its public key; there's no separation between "identity" and "spend authority" the way there is with, say, a rotatable database password. "Rotating" a wallet key would mean generating a new keypair and moving every coin from the old address to the new one — which is just a transfer, with transfer fees in time and gateway calls, not a security operation. Your node never retires or deletes a wallet's key once generated; every key it has ever minted stays live forever, because old wallets may still hold funds mid-sweep or be referenced in historical records.
If you believe a specific wallet's key has been compromised (e.g. you
suspect a backup file leaked — see backup-restore.md):
- Do not wait — treat it as urgent. The blast radius of one leaked wallet key is exactly that wallet's balance, no more (it doesn't expose your admin account or other wallets), but that balance is fully at risk.
- Move funds out of the affected wallet immediately via a manual outbound
transfer to a wallet you're certain is safe (see
treasury-operations.md) — this is the closest equivalent to "rotating" a compromised key: you're evacuating value from the compromised address, not replacing the address itself. - Stop using the compromised wallet as a sweep target or treasury source going forward — it can be left empty and idle, but its key stays in your vault; there's no delete.