Skip to main content
The Totalis API accepts two authentication schemes:
  • API key — for programmatic clients (bots, scripts, server-side integrations). Sent as the X-API-Key header. Works on both REST and WebSocket.
  • Privy JWT — used by the web dashboard. Sent as Authorization: Bearer <jwt>. The session signer underpinning the JWT also signs vault transactions in the browser.
Either scheme works on every authenticated endpoint, with one exception: POST /v1/api-keys (create a new API key) requires a Privy JWT, or an API key that holds the keys:manage scope.

​
Getting your API key

Generate an API key from the Totalis Dashboard:
  1. Log in to app.totalis.trade
  2. Navigate to your account settings
  3. Create a new API key, name it, and choose its scopes (see below)
  4. Copy the full key immediately
The full API key is only displayed at creation time. Save it securely — you will not be able to retrieve it later.

​
Using your API key

Send your API key in the X-API-Key header with every request:
For WebSocket connections, authenticate after connecting:

​
Scopes

Every API key carries a set of scopes — the capabilities you select at creation. A request to an endpoint whose scope the key lacks is rejected with 403 (insufficient_scope). Grant only what a given integration needs.
A read-only integration (dashboards, reconciliation) needs only the *:read scopes. A trading bot adds trading:write (and funds:deposit if it tops up the vault). Reserve funds:withdraw, tx:sign, and keys:manage for keys that genuinely need them — each can move funds or escalate.

​
Managing API keys

You can list, create, and revoke API keys programmatically (or from the Dashboard):
  • List keys — GET /v1/api-keys
  • Create key — POST /v1/api-keys (requires a Privy JWT, or a key with keys:manage)
  • Revoke key — DELETE /v1/api-keys/{prefix}
A new key can never grant a scope the creating credential doesn’t already hold.

​
Key lifecycle

  • Active — the key is valid and can be used for authentication.
  • Revoked — the key has been manually revoked and will be rejected.
  • Expired — the key has passed its expiration date.