Skip to main content

Managing your API key

Your API key is the credential your server presents on every request (see API keys for how it authenticates). Keys are minted, rotated, and revoked by a superadmin in the portal — each of these is a sensitive action, so the portal asks for a fresh 2FA step-up first.

A credential a program could mint or replace on its own is a credential that spreads without anyone deciding to spread it — so key management stays with a human in the portal, never the machine API.

Issue a key​

  1. Sign in to the portal and open API keys.
  2. Choose Generate key.
  3. Optionally give it a label (so you can tell your keys apart later) and an expiry — either a duration or an end date. Leave both empty for a key that never expires.
  4. Complete the 2FA step-up.
  5. Copy the secret now. It is shown only on this screen; Orbitum stores only a hash and can never show it again.

You can hold up to five live keys per partner. At the limit, generating another returns CEX_API_KEY_CAP_EXCEEDED — revoke one you no longer use first. A sensible allocation is one key per environment plus a spare for rotation, e.g. prod-active, prod-rotating, staging, sandbox, and a break-glass key.

Rotate a key​

Rotation issues a replacement while the old key keeps working for a short grace window (24 hours by default, up to 7 days), then expires. That overlap is what lets you swap keys with zero downtime:

  1. Rotate the key in the portal — you receive a new secret (shown once).
  2. Deploy the new secret to your servers.
  3. Confirm your traffic is running on the new key.
  4. Let the old key expire at the end of the grace window.

Rotate — don't renew in place. And don't wait until an expiry is imminent: a key that's already expired or revoked can't be rotated (CEX_API_KEY_ROTATE_CONFLICT).

Revoke a key​

Revoking a key invalidates it immediately — any server still presenting it gets 401 CEX_UNAUTHORIZED. Revoke is the right move the moment a key might have leaked (seen in a commit, a log, or a screenshot); treat any exposed key as compromised. Revoking is idempotent, so retrying is safe.

Revoking a key never affects orders — key lifecycle and order lifecycle are independent.

Watch your keys​

The portal lists your keys with metadata only — the key prefix, status, when it was created, when it expires, and when it was last used. The secret itself is never shown again after creation. Use last used to spot a key you can safely revoke, and expires to plan a rotation before it lapses.

Handling the secret in your systems​

  • Keep keys server-side only — never in browser or mobile code.
  • Load them from environment variables or a secrets manager, never from source control.
  • Use a separate key per environment so a leaked sandbox key never touches production, and revoking one never breaks the other.
  • Never log a key or put it in a URL or query string — headers stay out of request logs and browser history.
  • Rotate on a schedule, and immediately on any suspected exposure.