SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-10
Browse: SET Merchant API

SET Merchant API · API keys

Rotate an API key, with an overlap

POST/v1/api_keys/{id}/rotate

Key scope: write · Success: 201

A new key, shown once, with the old key's scopes, label, allowedCidrs and pinned SET-Version. The old key keeps working for the overlap, so you can deploy the new one without downtime, and then answers 401 api_key_expired. A key may rotate itself. Event api_key.rotated, which never carries the key.

Path parameters

id stringrequired
The key's id.

Headers

Idempotency-Key string
Optional. The same key and body run once; a replay answers with Idempotent-Replayed: true. Kept 24 hours.

Body

overlapHours integer
0–72, default 24. The overlap never runs past the old key's own expiry.
expiresAt ISO time
The new key's expiry, at least a minute ahead. Null or absent means no expiry.

Notes

  • A key can be rotated once: a second rotation is 409 api_key_already_rotated. A revoked or expired key is 409 api_key_inactive; issue a new key instead.

Errors

  • 400 overlap_invalid
  • 400 expires_at_invalid
  • 403 scope_exceeds_caller
  • 403 operator_cannot_issue
  • 404 api_key_unknown
  • 409 api_key_inactive
  • 409 api_key_already_rotated
  • 409 too_many_keys
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 401 api_key_expired
  • 403 scope_missing
  • 403 platform_api_paused
  • 429 rate_limited
  • 503 api_disabled

All codes: Errors.