Authentication

API keys, scopes, IP allowlists, and key rotation.

Every data route on api.kash.bot requires an API key. The only unauthenticated endpoints are the infra-meta routes: /v1/health, /v1/ready, /v1/openapi.json, /v1/docs.

The X-API-Key header

Pass your key on every request as the X-API-Key header:

curl https://api.kash.bot/v1/markets \
  -H "X-API-Key: kash_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Keys are issued via the webapp’s Settings → API Keys page or the admin CLI.

With @kashdao/sdk you don’t set the header yourself — construct the client with your key and it authenticates every request (and auto-routes to staging for a kash_test_* key, production for kash_live_*):

import { KashClient } from '@kashdao/sdk';
const kash = new KashClient({ apiKey: process.env.KASH_API_KEY! });

Key format

kash_live_<32 base62 chars>   # production
kash_test_<32 base62 chars>   # staging

The 32-character random suffix gives roughly 190 bits of entropy. The prefix is informational — the server validates the full key against a stored HMAC under a server-side pepper. Never log or commit the plaintext.

Scopes

A scope is a coarse-grained permission. Every endpoint declares the scope(s) it requires. The requireScope middleware fails closed with 403 INSUFFICIENT_SCOPE when a key lacks one.

Scope	What it grants
markets:read	GET /v1/markets, GET /v1/markets/{id}, GET /v1/markets/{id}/predictions
markets:quote	GET /v1/markets/{id}/quote
portfolio:read	GET /v1/portfolio, GET /v1/portfolio/positions
trades:read	GET /v1/trades, GET /v1/trades/{id}, GET /v1/traces/{id}
trades:write	POST /v1/trades, POST /v1/trades/{id}/confirm
webhooks:manage	GET /v1/webhooks/events, POST /v1/webhooks/events/{id}/redeliver, POST /v1/auth/api-keys/me/webhook-secret/rotate
auth:manage	GET /v1/account/usage

Default scopes by tier. Self-served free and developer keys default to markets:read, markets:quote, portfolio:read. Admin-issued enterprise and mm keys add trades:read, trades:write. You can override at issuance — request the scopes that match your use case, no more.

Tiers

Each key has a tier that governs default rate limits and spending caps. See Rate Limits for per-tier quotas.

Tier	How issued	Notes
free	Self-serve via webapp	Conservative caps. Default for new accounts.
developer	Self-serve, paid	Higher rate limit and per-trade caps.
enterprise	Admin-issued (contractual)	Custom rate limit. Required for governance-thresholded operations.
mm	Admin-issued only	Market-maker tier. High caps. Discretionary review required.

Reach out to [e-mail] for enterprise or mm keys.

IP allowlists

Optional per-key. When set, requests from any IP not in the list fail closed with 403 IP_NOT_ALLOWED before the route handler runs.

Format: comma-separated IPv4/IPv6 addresses or CIDR ranges. Set in the webapp UI or via the admin CLI at issuance time.

10.0.0.0/8,2001:db8::/32,203.0.113.45

We strongly recommend setting an allowlist for production keys. It collapses an entire class of “key was leaked from a logfile” incidents.

Key rotation

API keys do not expire automatically. Rotate them when:

• A team member with access leaves
• A key may have been logged or committed to a repo
• You’re tightening security posture before a major release

To rotate:

1. Issue a new key in the webapp.
2. Roll it out to your services.
3. Verify the new key is in use (check /v1/account/usage — request counts on the old key should be zero).
4. Revoke the old key in the webapp.

There is no automated dual-validity overlap window for API keys; the rotation is sequential. (Webhook secrets do have a 7-day rotation overlap — see Secret Rotation.)

Body signing for trades:write (optional, hardened)

For write routes like POST /v1/trades, you can opt into HMAC-signed request bodies as a defence-in-depth layer against captured-request replay and in-flight tampering. Send the signature in X-Kash-Signature using the same Stripe-style header format as our webhook signatures:

X-Kash-Signature: t=<unix-ms>,v1=<hex-hmac-sha256>

• Signing secret = your API key plaintext (the same value you send in X-API-Key). No separate signing secret is issued — this is not the key’s webhook_secret.
• Canonical input is <unix-ms-timestamp>.<METHOD>.<path>.<raw-body> — the timestamp from t=, the HTTP method uppercased, the URL pathname without the query string (query params aren’t signed because intermediaries often re-order them), and the exact raw body bytes you send.
• Algorithm: HMAC-SHA256, hex-encoded.
• Timestamp tolerance: ±5 minutes. Older or newer timestamps are rejected.

import { createHmac } from 'node:crypto';

const ts = Date.now();                       // unix milliseconds
const canonical = `${ts}.POST./v1/trades.${rawBody}`;
const sig = createHmac('sha256', apiKeyPlaintext).update(canonical).digest('hex');
// Header: X-Kash-Signature: t=<ts>,v1=<sig>

If the header is present, the server MUST be able to verify it — a mismatch, a malformed header, or a stale timestamp is rejected with 401 REQUEST_SIGNATURE_INVALID. If absent, the route still works (the API key is the canonical authentication). Multiple comma-separated v1= values are accepted (for graceful scheme rotation later). Use body signing when your threat model includes a compromised TLS-terminating proxy or leaky request logs.

Auth failures

Status	code	Meaning
401	API_KEY_MISSING	No X-API-Key header.
401	API_KEY_MALFORMED	Header present but not a well-formed key.
401	API_KEY_INVALID	Key not recognised, or HMAC mismatch.
401	API_KEY_REVOKED	Key was found but has been revoked.
401	API_KEY_EXPIRED	Key is past its expires_at timestamp.
403	INSUFFICIENT_SCOPE	Key is valid but doesn’t carry the scope this route requires.
403	IP_NOT_ALLOWED	Source IP not in this key’s allowlist.
401	REQUEST_SIGNATURE_INVALID	Body-signing was opted into and failed verification.

All auth failures return RFC 7807 application/problem+json and are written to the per-key audit log. Repeated failures from the same source trigger the per-IP brute-force lockout.

Inspecting auth state

The GET /v1/account/usage endpoint returns telemetry for the calling key — including 24h auth-failure and rate-limit-rejection counts. Useful for spotting key misuse early.

curl https://api.kash.bot/v1/account/usage \
  -H "X-API-Key: $KASH_API_KEY"

Next

Rate Limits

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

Errors

RFC 7807 error format and the full error code catalog.