Skip to main content
You use two kinds of key. Your first key is the management key. You create it on Profile in the web app. It runs your account but never places an order. It also creates every trading key, one per subaccount. We receive only the public half of each keypair.
  • The management key opens, funds, and labels subaccounts. It also creates and revokes keys.
  • A trading key places and cancels orders. It also streams the order book and your fills.
  • You create the management key on Profile → Settings → Novig API.
  • You create a trading key with POST /v3/account/subaccounts, signed by the management key.
In these docs, the management key file is novig-api-key-mgmt-1.pem and a trading key file is desk-1.pem. These routes manage keys:

​
Create your management key

1

Open the Novig API screen

Open Profile on paper.novig.com or on novig.com, then press Settings and Novig API. The screen lists your keys and shows your location check result.
2

Name the key

Press Create Key and enter a nickname, which is only a label and grants no access. The browser generates the keypair with Ed25519, or with P-256 if it can’t generate Ed25519.
3

Confirm

Press Confirm Key Creation. The browser downloads novig-api-key-<nickname>.pem, a PKCS#8 PEM file, and shows the private key once.
4

Save the private key

If the browser blocked the download, copy the key from the screen. Then press I’ve saved my key, and we never show the private key again.
Store the private key in a secret manager before you press I’ve saved my key. We never hold the private key, so we can’t show it again.
The key ID shown beside the private key identifies your management key. Send it in the Novig-Key-Id header. If you lose the private key, revoke the key on the same screen and create a new one. Your web session is the only recovery path. Until you revoke the key, anyone who holds the private key can act as that key.

​
Create other keys with the API

A route creates every key below management. Generate the keypair before you call the route:
Then send the public key in the request body:
  • name is a label that appears in the key list.
  • publicKey is the public key as an SPKI PEM, newlines included.
  • algorithm must match the key material.
  • expiresAt must be strictly in the future. Never set it on a management key, as Revoke a key explains.
POST /v3/keys and POST /v3/account/subaccounts take no scope field. If the body includes one, the route returns 400. POST /v3/account/subaccounts/{keyId}/keys requires one: trading or trading::read. The route returns the new key: Pick Ed25519 unless a hardware requirement forces P-256. Your signer must use the same algorithm. To compute the fingerprint yourself, run:

​
How a key gets its scope

Each key has a scope, which sets what it can reach and do. Where you create a key decides its scope, so you never name one yourself. Profile creates the management key and generates its keypair in the browser. A route creates every other key from a public key that you generate.
Web sessionA bearer JWT

Profile → Settings → Novig API

managementOne live per trader

Creates the rest with a route

management::read live per trader
tradingOne live per subaccount
trading::read live per subaccount

Each line points from a credential to the key it creates.

The route that opens a subaccount also creates its trading key. A subaccount has one live trading key. After you revoke it, POST /v3/account/subaccounts/{keyId}/keys creates its replacement. The same route creates up to live trading::read keys beside it.

​
Why keys work this way

  • Your web session is the root. Its bearer JWT is the only credential you hold before your first key, and the only way to a management key.
  • Every key has its own keypair.
  • No key creates a key above itself. Every route that creates a key accepts only a management key or your web session, so a leaked read or trading key can’t escalate.
  • A subaccount and its trading key are created together, so no wallet exists without a key. After you revoke that key, POST /v3/account/subaccounts/{keyId}/keys creates its replacement.

​
Limits

​
Location checks

Every signed route runs two location checks. If either check fails, the route returns 451. A cancel skips both.
  • IP check: refuses a request from a restricted state, or through a VPN, proxy, or Tor exit. A data-center address is fine.
  • Companion check: refuses a key holder whose last device geolocation is missing, failed, named no region, or came from a restricted state. A placement also refuses one older than days. A read admits it.
To pass the companion window check, open the Novig app so your device geolocates. The refusal lasts until the key holder geolocates again. The Novig API screen shows your check result before you create your first key. If a window is open, the screen also shows when it expires.

​
Revoke a key

To revoke a key, press × beside it on Profile → Settings → Novig API. You can also call DELETE /v3/keys/{id}. Revocation takes effect within s, and you can’t undo it.
Revoking a key leaves its resting orders on the book. Cancel them before you revoke the key.
If the key is compromised, change the order. Revoke it first, then create a replacement, then cancel the resting orders.
An expired management key still takes the only management slot, and it can’t sign its own revocation. Never set expiresAt on a management key.

​
Rotate a key

  • management: revoke the old key, then create a new one. There’s a gap with no key.
  • management::read: create the new key, switch over, then revoke the old one. There’s no gap.
  • trading: revoke, then create the replacement with POST /v3/account/subaccounts/{keyId}/keys. There’s a gap, so cancel orders first.