GET endpoints authenticate with an opaque bearer secret in a header — X-API-KEY or X-DEVICE-KEY — not a signature. Both are minted by a session-signed call, returned once, and presented as a header value on every read.
Reads only carry these credentials. Writes — orders, cash, key management — are signed by a session key, whose scope sets the ceiling for any credential it mints.
Both credentials work in the API reference playground: paste a key into the X-API-KEY or X-DEVICE-KEY field and run a GET against your hosted URL.
The two read credentials
- What it is: an opaque base64 string, minted by a session-signed call.
- Presented as: the
X-API-KEY header.
- Authorizes: read endpoints — account, orders, fills, positions, funding, leverage, sessions.
- Use for: headless, programmatic read access.
- What it is: an opaque base64 secret, minted by a session-signed device login.
- Presented as: the
X-DEVICE-KEY header.
- Authorizes: the same reads as
X-API-KEY, plus minting device pairings and WebSocket tickets, and self-revocation.
- Use for: clients that also open the private WebSocket or pair a device.
+ / / alphabet, = padding). For where each one sits in the full credential map, see Credentials.
Which reads accept which
Account, orders, fills, positions, funding, leverage, and session reads accept either header. Send one; do not send both.
Minting a device pairing or a WebSocket ticket needs the device’s own identity, so those accept only X-DEVICE-KEY — an API key is rejected.
Each endpoint in the Trading API reference lists the header it accepts. When an endpoint lists only X-DEVICE-KEY, an API key does not satisfy it.
Pinned vs unpinned scope
Both read credentials carry a scope fixed at mint time, and can never reach further than the session that minted them. An unpinned credential is account-wide and reaches every subaccount on its account; a pinned credential reaches only the one subaccount it is pinned to. Minting an account-wide read credential therefore requires a session that already reaches the whole account.
Listing endpoints fail closed: a pinned credential sees only resources within its reach, and rows it cannot precisely authorize are omitted rather than returned. An empty list is not an error.
When a pinned credential requests a subaccount or portfolio it does not reach, the exchange returns 404 Not Found, not 403 — out-of-scope resources are reported as if they do not exist. A 404 on a read you expected to succeed usually means the credential is pinned to a different subaccount.
Secrets are returned once
An API-key or device-key secret is returned exactly once, in the body of the minting call. The exchange keeps no recoverable copy and offers no “show secret again” call. Store it immediately.
- Listing returns prefixes only. Listing API keys or device keys returns the first 8 characters of each key plus metadata — never the raw secret.
- If you lose a secret, rotate. Mint a replacement, then delete or revoke the lost credential.
- A device key self-revokes. Logging out revokes the device key. Already-minted WebSocket tickets stay valid until they expire.
Reading the response
A GET that passes authentication returns 200 with the resource. Authentication and scope failures surface as transport-level errors:
| Status | Meaning | What to do |
|---|
200 | Read succeeded | Use the body |
401 | Missing or invalid read credential | Check the header name and the key value |
404 | Resource not found, or out of the credential’s scope | Confirm the credential reaches the target subaccount |
application/problem+json; see the error model for how to read them. For 429 and 413, see rate limits. 
