> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Key format, scopes, presets, expiry, rotation, and IP allowlists.

Every request needs an API key in the `Authorization` header. Keys belong to a project inside your workspace.

```
Authorization: Bearer $HYPERDASH_API_KEY
```

## Key format

```
hdk_sk_live_v1_<key id>_<secret>_<checksum>
```

| Part | Meaning |
| - | - |
| `hdk_sk_` | Hyperdash secret key prefix, chosen so secret scanners can recognize leaked keys. |
| `live_` or `test_` | Live keys read production data and are billed. Test keys return sample data and cost nothing. |
| `v1_` | Key format version. |
| Key id | 26 characters, public. |
| Secret | 43 characters (256 random bits). We store only a keyed hash. The console shows the secret's last 4 characters. |
| Checksum | 8 hex characters (CRC-32C of everything before it), so a mistyped key is rejected immediately. |

## Live and test keys

| | Live | Test |
| - | - | - |
| Data | Production | Fixed sample data (`meta.sample: true`) |
| Cost | Billed in credits | Free |
| Needs an active plan | Yes (`403 plan_required` otherwise) | No |
| Rate limits | Your plan's limits | 5 requests per second, burst 10, 2 concurrent |
| Streams | Live events | A synthetic event every 2 seconds |

Use test keys in CI and while you build.

## Scopes

| Scope | Grants |
| - | - |
| `markets:read` | Market data |
| `accounts:read` | Account state and history |
| `liquidations:read` | Liquidation events, by-market totals, and cascades. Other liquidation endpoints need `markets:read` or `analytics:read`; the reference lists each endpoint's scope. |
| `analytics:read` | Analytics, leaderboards, cohorts, and wallet lists |
| `streams:read` | WebSocket streams |
| `usage:read` | Workspace credit balance in `GET /v1/me` |

Every scope is read-only. A request outside the key's scopes returns `403 insufficient_scope` and costs nothing.

### Presets

| Preset | Scopes | Extra limits | Default expiry |
| - | - | - | - |
| All (default) | Every scope | None | 90 days |
| Agent | Every scope | 5 requests per second, 10,000 credits per UTC day, 2,000 credits per request | 30 days |
| Custom | Any subset | None | 90 days |

**Read only** grants the same access as **All**, since every scope is read-only.

You can change a key's scopes later in the console. Widening them requires your second factor if two-factor sign-in is on.

## Per-key limits

[Agent](#presets) keys carry their own limits on top of the plan. Other keys use the plan limits only, since the console cannot set limits on them.

* **Rate limit:** requests per second, with a burst of twice that. Exceeding it returns `429 rate_limited`.
* **Credit budget:** credits per UTC day. Exceeding it returns `403 credits_exhausted`.
* **Per-request maximum:** a request whose maximum cost is higher is refused with `403 max_credits_exceeded` before it runs.
* **IP allowlist (any key):** a list of CIDR ranges. Requests from other addresses return `403 ip_not_allowed`. A workspace policy can require an allowlist on every key.

## Expiry, rotation, and revocation

* **Expiry:** 30, 90 (default), or 120 days, capped by the workspace maximum. Keys that never expire are available only if a workspace admin allows them and no maximum is set. An expired key returns `401 expired_key`.
* **Rotation:** **Rotate** issues a replacement with the same scopes, allowlist, and limits. The old key keeps working for an overlap you choose: none, 1 hour, 24 hours (default), or 7 days, but never past its own expiry. Revoked and expired keys can't be rotated.
* **Revocation:** takes effect within about 5 seconds. A revoked key returns `401 revoked_key` and stays listed in the console for audit.

> [!WARNING]
>
> Keep keys on your server. Never ship a key in a browser bundle, mobile app, or public repository: anyone holding it can spend your credits. Browser apps should call your backend, and your backend calls us.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.