Skip to main content
Every data route on api.kash.bot requires an API key. Only /v1/health, /v1/ready, /v1/openapi.json and /v1/docs are open.

​
The X-API-Key header

Send your key on every request as X-API-Key. Send exactly one: a request with two X-API-Key headers is refused.
Keys are issued in the Kash web app under Settings → API Keys. The plaintext is shown once. A user can hold at most 5 active keys.
With @kashdao/sdk you don’t set headers yourself. Construct the client with your key and it authenticates every request; a kash_test_ key goes to staging and a kash_live_ key to production.

​
Key format

The server stores only a keyed hash of each key, never the plaintext. Never log or commit a key.

​
Scopes

Each key carries a set of scopes, and each route requires one. A key without the route’s scope gets 403 INSUFFICIENT_SCOPE. A key created without an explicit scope list gets markets:read, markets:quote and portfolio:read. Choose the scopes you need when you create the key, and no more: a read-only analytics key should never carry trades:write.

​
Tiers

Each key has a tier, which sets its rate limit and spending caps. See Rate limits for the numbers.

​
Account status

A key belongs to the account that created it in the web app. If that account is suspended or closed, its keys are refused with 403 ORGANIZATION_INACTIVE.

​
IP allowlists

Optional, per key. When a key has an allowlist, a request from any other address is refused with 403 IP_NOT_ALLOWED before the route runs. Entries are IPv4 or IPv6 addresses or CIDR ranges:
Set it on the key in the Kash web app. We strongly recommend an allowlist for production keys.

​
Request signing (optional)

You can sign requests with an HMAC as a defence against tampering and replay of a captured request. Send X-Kash-Signature (exactly one) in the same format as webhook signatures:
  • Secret: your API key plaintext, the value you send in X-API-Key.
  • Signed input: <t>.<METHOD>.<path>.<raw-body>: the timestamp from t=, the HTTP method in upper case, the URL path without the query string, and the exact body bytes (empty for a GET).
  • Algorithm: HMAC-SHA256, hex-encoded. Several v1= values are accepted; one must match.
  • Tolerance: the timestamp must be within 5 minutes of the server’s clock.
A present signature must verify: a mismatch, a malformed header or a stale timestamp is 401 REQUEST_SIGNATURE_INVALID. Signing applies to every authenticated route. It is optional unless your key has been set to require signing, in which case an unsigned request is also refused with 401 REQUEST_SIGNATURE_INVALID. Because the signing secret is the key itself, signing protects body integrity and limits the replay window of a captured request. It does not protect you against a stolen key.

​
Key rotation

Rotate a key when someone with access leaves, when a key may have been logged or committed, or as routine hygiene:
  1. Create a new key in the Kash web app.
  2. Roll it out to your services.
  3. Confirm the old key has gone quiet (GET /v1/account/usage with the old key shows no new trades).
  4. Revoke the old key. Revocation takes effect immediately (401 API_KEY_REVOKED).
Keys can carry an expiry date; an expired key gets 401 API_KEY_EXPIRED. API keys have no overlap window. Webhook secrets do: see Secret rotation.

​
Auth failures

Failed authentication is counted per source address: too many failures in a short window lock that address out for a period, answered with 429 RATE_LIMIT_EXCEEDED and a Retry-After header.

​
Next

Rate limits

Per-tier quotas, the X-RateLimit-* headers and 429 handling.

Errors

The RFC 7807 error format and the code catalogue.