Authentication

Every /v1/* account endpoint takes an API key in the x-api-key header. On the WebSocket, send {"op":"auth","apiKey":"hb_…"} before subscribing to the account channel.

Keys are shown once

A key is stored as a SHA-256 digest, never in the clear. The value crosses the wire at mint time and lives only in your client; the server keeps the hash. So a key is shown exactly once — at creation — and cannot be recovered, only replaced. Save it when you mint it.

Keys are provisioned two ways: POST /v1/signup (testnet self-serve, no operator action) and, for operators, an admin route. Both mint a full-scope master key.

Scopes

Each key carries a set of capabilities. They are independent, not a ladder — trade does not imply read. Ask for exactly the set you need.

scope	grants
read	account / positions / orders / history reads · the WS account channel
trade	orders, cancels, withdrawal quotes, deposit invoices, referral ops
withdraw	POST /v1/withdrawals
admin-sessions	mint and revoke sessions (POST /v1/sessions, /v1/sessions/revoke)

A call whose key lacks the route's scope is refused with 403 {"code":"insufficient_scope"}. Scopes restrict which key may act, never when: a withdraw key still withdraws in every halt mode.

The delegate-key pattern

This is the intended shape for an agent, and the reason scopes exist:

1. Sign up, get the master key, and put it cold.
2. Mint a ["read","trade"] delegate with POST /v1/sessions for the bot loop.
3. Run unattended on the delegate.

A stolen delegate key can lose you a position; it cannot touch your balance, because it has no withdraw scope. Minting intersects the requested scopes with the minter's own, so a key can never mint a more capable key than itself.

Minting is a privileged operation: it draws the order rate budget, and an account may hold at most a fixed number of live keys at once (see Rate limits). Beyond that, revoke an unused session before minting another.

Bearer-token threat model

The key is a bearer credential — whoever holds it can act within its scopes. Treat it like a secret: never log it, never put it in a URL, scope it down for anything unattended, and rotate by minting a new key and revoking the old. There is no password or account-recovery flow behind a key; possession is the credential.