Skip to main content
A master key is the root of trust for an account. You generate it off-exchange and register its public key when you create the account or add it later. The exchange stores only the public key and a role; it never holds your private key. Master keys do two jobs: they mint and revoke session keys, and they manage other master keys. They do not sign day-to-day trading. For that, a master key mints an Ed25519 session key and the session signs your orders and cash movements. SDKs are coming soon; for now you generate master key material yourself and sign requests by hand — see Signing requests for the envelope and the per-curve byte rules.

​
Two flavours

A master key is one of two types, interchangeable for every master-key operation. The wire signature_type selects which one signed the request.
  • Curve: secp256k1.
  • Public key: 33-byte compressed, base64-encoded in the request body.
  • On the wire: the Base64SignedPayload envelope with signature_type = 1.
  • You sign: the EIP-712 digest of the payload, with your secp256k1 private key.

​
Admin vs scoped

A master key carries one of two reaches. Reach is independent of the FullAccess / TradingOnly role the key also carries: the role limits which operations the key can authorize, reach limits which subaccounts it touches.

Admin master key

Reaches the whole account — every subaccount, present and future. Required to add or remove other admin keys, add or remove scoped keys, and to root the unpinned sessions that authorize account-level operations.

Scoped master key

Pinned to one subaccount. Mints sessions only within that subaccount’s reach. Cannot manage other keys and cannot promote itself or another key to admin.
Only an admin key can add or remove another admin key (POST /api/v1/auth/admin-keys/add, .../remove) or a scoped key (POST /api/v1/auth/scoped-keys/add, .../remove). Scoped keys cannot promote each other.
The exchange refuses to remove the last admin key (master_key_rejected_last_key), and a key cannot remove itself (master_key_rejected_self_removal). An account must keep at least one admin master key, or it can no longer manage its own keys.

​
Per-account caps

An account holds a limited number of master keys — admin keys per account, scoped keys per subaccount. A request that would exceed the limits is rejected with master_key_rejected_invalid. Register the keys you need and avoid churn.

​
What a master key authorizes

A master key signs account and key-management operations. It does not sign trading or cash writes directly — it mints a session for that.
OperationEndpointReach required
Mint a session keyPOST /api/v1/auth/sessionsAny master key
Revoke a session keyPOST /api/v1/auth/sessions/revokeAny master key (a session it can see)
Add / remove an admin keyPOST /api/v1/auth/admin-keys/add, .../removeAdmin
Add / remove a scoped keyPOST /api/v1/auth/scoped-keys/add, .../removeAdmin
When a master key mints a session, the session inherits the key’s reach. An unpinned session minted under an admin master key is admin-rooted and reaches the whole account; a pinned session, or any session under a scoped key, is not. Admin-rooted sessions authorize subaccount creation and withdrawals.

​
Reading the response

Master-key writes return a RequestAck — { status, processed_at_ns }. The status is the outcome: these calls return HTTP 200 even on rejection, so a 200 with a rejected_* status is a rejection, not an acceptance. Always read the body (error model). Master-key statuses:
  • master_key_added, master_key_removed — applied.
  • master_key_rejected_invalid — the key material or request is invalid.
  • master_key_rejected_unauthorized — the signer is not authorized to manage this key.
  • master_key_rejected_self_removal — a key cannot remove itself.
  • master_key_rejected_last_key — cannot remove the last admin key.

​
Keep the private key safe

You generate master key material off-exchange; the exchange only ever holds the public key. There is no recovery. Losing every admin master key with no replacement leaves the account unmanageable — you can no longer mint sessions or manage keys. Register more than one admin key, or back up your authenticator, before you rely on the account.