AuthenticationRotating & revoking keys

Rotating & revoking keys

When to rotate

  • A teammate who had access leaves the company
  • A key accidentally got committed to a public repo, posted in chat, screenshotted, or otherwise exposed
  • It’s been more than 12 months since the last rotation (recommended hygiene)
  • A laptop with the key on disk was lost or stolen

If in doubt, rotate. There’s no penalty for a rotation, only for a leak.

How rotation works

Soxara supports zero-downtime rotation: you mint a new key alongside the existing one, deploy the new key to your services, confirm everything’s flowing, then revoke the old key.

  1. Mint the new key in the business dashboard.
  2. Deploy the new key to every service that uses Soxara — most teams update an env var and roll out their service. During the rollout, the OLD key still works.
  3. Confirm by tailing your logs or watching the dashboard’s “API key activity” view — the new key should be the one receiving traffic.
  4. Revoke the old key. Click “Revoke” in the dashboard, or POST /v1/merchant/api-keys/{key_id}/revoke. Effective immediately.

Once revoked, any request bearing the old key returns 401 UNAUTHORIZED.

Emergency revocation

If a key is actively compromised, skip the rollout step and revoke immediately. The old key stops working; the new key (you may not have rolled it out yet) takes over. Your services will see 401s on every call made with the old key until they pick up the new one — expect a brief outage.

This is the right call: a few minutes of outage is much better than an attacker continuing to charge cards.

Revocation propagation

Key revocation is near-immediate but not instantaneous. The gateway caches verified keys in Redis for up to 30 seconds. After revocation, you may see up to 30 seconds of “successful” requests with the revoked key before all gateway nodes pick up the change.

The cache TTL is intentionally short. We don’t increase it.

Don’t reuse a revoked key prefix

Revoked keys are kept in our database for 90 days for audit purposes, then deleted. We never re-issue a previously-used prefix. If you see sxm_live_AbCdEfGh again, it’s the same key — never a different one.

Listing your keys

curl https://api.soxara.com/v1/merchant/api-keys \
  -H "Authorization: Bearer $SOXARA_KEY"

Returns each key’s id, prefix, name, scopes, created_at, last_used_at, and revoked_at (null if active). The secret tail is never returned — only the prefix.

Use last_used_at to spot keys that aren’t actually in use and can safely be revoked.

ScopesErrors