Rotate an API key without downtime

Replace an API key with no failed requests: create a second key, deploy it, confirm it is in use, then revoke the old one. Plus what to do when a key leaks.

What you will do

In Credentials, Rotate replaces a key's secret and the old secret stops working immediately. To avoid failed requests during a planned change, run two keys side by side for a moment instead. You can have up to 20 active keys per account (Live and Test each).

Portal access, with the owner contact saved (key actions are refused without it).
For Live keys: live mode approved.
Access to every place the key is stored (secret manager, server environment, plugins).

Steps (planned rotation)

Find where the key is used
Open Credentials on the right side (Live or Test). Each key shows when it was last used, the IP and user agent, and a 30-day request history. Note every integration using the old key.
Create the replacement
Click Create key with a new name (for example "Backend 2026-11"). Copy the key when it is shown.
Deploy it everywhere
Update VEXPAY_API_KEY in each environment and plugin that used the old key, and redeploy.
Confirm the new key is in use
Call GET /v1/banks with the new key. Then check Credentials: the new key shows a recent "Last used", and the old key's stops moving.
Revoke the old key
Click Revoke on the old key. It stops authenticating at once; its payment history is kept.

Smoke testbash

curl "${API_URL}/v1/banks" \
  --header "x-api-key: ${VEXPAY_API_KEY}"
# 200 = the new key works · 401 = wrong, revoked or rotated key

If a key leaked

Stop it now
Click Rotate (you get a new secret for the same key) or Revoke on the exposed key. Do this before updating your servers: a short outage is better than a working leaked key.
Deploy the new secret
Update every environment with the new secret and check with GET /v1/banks.
Review the access history
In Credentials, look at the last 30 days of requests for IPs or user agents you do not recognise, and check Payments and Payouts for activity you did not start.
Tell VEXPay
Contact VEXPay with what you found so the team can review the account with you.

Check that it worked

Only the new key shows recent use in Credentials; the old key is marked Revoked.
No 401 responses in your logs after the switch.
If you subscribe to them, you received tenant.api_key.created, tenant.api_key.rotated or tenant.api_key.revoked.

If something goes wrong

Symptom	Likely cause	What to do
401 right after the change	A service still sends the old (revoked or rotated) secret	Find it from the old key's last-used IP and user agent, and update it.
409 `owner_contact_required`	No owner email and phone saved	Save them in the portal prompt, then retry.
403 `live_mode_not_activated` when creating a live key	Live mode is not approved yet	Use Test keys until approval (see Go live).
Cannot create another key	The account already has 20 active keys	Revoke keys you no longer use.

A rotation affects only the mode it is done in: rotating a Test key never touches Live. Related: Authentication