Skip to main content
POST
Rotate an API key

What this endpoint does

Issues a replacement API key that inherits the retiring key’s scopes and IP allow-list. The replacement has a new key ID; the retired key becomes status revoked with rotatedToId pointing at its replacement.

When to use it

Rotate routinely and immediately after suspected exposure.

Before you call

Manage keys from a console session with a recent second-factor (MFA) confirmation — a request authenticated only with an API key is refused with 403 step_up_required — and pass a key ID owned by the same tenant account. Prepare to update the consuming service.

Money and balance effect

This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money.

States and completion

The new secret is returned once, on this response only. The old secret stops authenticating the moment rotation succeeds — there is no grace period. Update stored key IDs as well as the secret: later update or revoke calls must target the replacement key’s ID.

Safe retries

Send a unique Idempotency-Key for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read API keys for the complete workflow.

Authorizations

Authorization
string
header
required

Send the same Wayex API key as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response.

Required string length: 8 - 255

Path Parameters

id
string
required

Body

application/json
scopes
enum<string>[] | null
Required array length: 1 - 21 elements
Available options:
customers:read,
customers:write,
routes:read,
routes:write,
transfers:read,
transfers:write,
treasury:read,
treasury:write,
rates:read,
webhooks:read,
webhooks:write,
fees:read,
fees:write,
keys:read,
keys:write,
settings:read,
settings:write,
team:read,
team:write
allowedIps
string[] | null
Required array length: 1 - 50 elements
Required string length: 1 - 49
Pattern: ^[0-9a-fA-F:.]+(\/\d{1,3})?$

Response

The replacement key, including the new plaintext secret (shown once).

id
string
required
Minimum string length: 1
counterpartyId
string
required
Minimum string length: 1
kind
enum<string>
required
Available options:
secret,
publishable
name
string
required
Minimum string length: 1
maskedKey
string
required
Minimum string length: 1
lastFour
string
required
status
enum<string>
required
Available options:
active,
revoked
createdAt
string<date-time>
required
secret
string
required
Minimum string length: 1
revokedAt
string<date-time>
rotatedToId
string
Minimum string length: 1
scopes
enum<string>[]
Available options:
customers:read,
customers:write,
routes:read,
routes:write,
transfers:read,
transfers:write,
treasury:read,
treasury:write,
rates:read,
webhooks:read,
webhooks:write,
fees:read,
fees:write,
keys:read,
keys:write,
settings:read,
settings:write,
team:read,
team:write
allowedIps
string[]
Required string length: 1 - 49
Pattern: ^[0-9a-fA-F:.]+(\/\d{1,3})?$