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

# Authentication

> API keys and how to use them.

Read endpoints work without a key. Send a key in the `Authorization` header for more history and a higher rate limit.

## Keyless access

Call any read endpoint with no `Authorization` header:

```bash theme={null}
curl "https://api.ironflow.sh/v1/trades?source=hyperliquid&market=BTC-PERP"
```

Keyless calls get 10 requests per minute per IP, 24 hours of history and 1 hour per request. Past the limit the API returns `429` with a link to get a key. Writes (custom cohorts) always need a key.

## Getting an API key

Enter your email at [ironflow.sh/key](https://ironflow.sh/key). The key arrives by email within a minute. Free keys get 60 requests per minute and 30 days of history. For paid tiers, [contact us](https://ironflow.sh/api).

API keys have the format `if_` followed by a random string.

## Using your key

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.ironflow.sh/v1/trades?source=hyperliquid&market=BTC-PERP" \
    -H "Authorization: Bearer if_your_api_key"
  ```

  ```typescript TypeScript theme={null}
  import { Ironflow } from "@ironflowsh/sdk";

  const client = new Ironflow("if_your_api_key");
  ```

  ```python Python theme={null}
  from ironflow_sdk import Ironflow

  client = Ironflow("if_your_api_key")
  ```
</CodeGroup>

## Key security

* **Never expose your key in client-side code.** Keys are server-side credentials.
* **Never commit keys to git.** Use environment variables.
* To rotate a key, request a new one at [ironflow.sh/key](https://ironflow.sh/key) and ask us to revoke the old one.

```bash theme={null}
# Good: load from environment
export IRONFLOW_API_KEY=if_your_api_key

# Good: use in code
curl "https://api.ironflow.sh/v1/trades?source=hyperliquid&market=BTC-PERP" \
  -H "Authorization: Bearer $IRONFLOW_API_KEY"
```

## Tier limits

Your key's capabilities depend on your tier:

| | No key | Free key | Explorer | Builder | Enterprise |
| - | - | - | - | - | - |
| **Price** | \$0 | \$0 | \$49/mo | \$149/mo | Contact us |
| **History** | 24 hours | 30 days | 90 days | 1 year | Everything stored |
| **Per-request window (with `market`)** | 1 hour | 6 hours | 24 hours | 7 days | Unlimited |
| **Per-request window (no `market`)** | 1 hour | 4 hours | 4 hours | 4 hours | 4 hours |
| **Rate limit** | 10 req/min per IP | 60 req/min | 100 req/min | 1,000 req/min | 10,000 req/min |
| **Analytics endpoints** | Basic | Basic | Basic | All | All |
| **Custom cohorts** | No | No | No | No | Unlimited |

Each tier inherits everything in the tier below it. Per-request windows are clamped server-side: requests exceeding the cap return `400 QUERY_WINDOW_EXCEEDED`. Paginate by issuing several smaller `from`/`to` requests.

## Errors

A malformed or unknown key returns `401 Unauthorized`. Sending no header is keyless access, not an error:

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key not found or deactivated. Free keys: https://ironflow.sh/key"
  }
}
```

Accessing a feature above your tier returns `403 Forbidden`:

```json theme={null}
{
  "error": {
    "code": "TIER_FORBIDDEN",
    "message": "this analytics endpoint requires Builder tier or above — net-flows and funding-stats are available on all tiers"
  }
}
```


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