> For the complete documentation index, see [llms.txt](https://mute-sh.gitbook.io/mute.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mute-sh.gitbook.io/mute.sh/api/getting-started/authentication.md).

# Authentication

Every mute.sh API key looks like `mute_<base62>` (e.g. `mute_ecoXcb…`). Create and manage keys in the dashboard at [app.mute.sh](https://app.mute.sh). One key works across the Data API, the gRPC block stream, and webhooks.

## Three ways to send it

```bash
# 1. X-API-Key header (recommended)
curl -H "X-API-Key: $MUTE_KEY" https://api.mute.sh/v1/markets/overview

# 2. Authorization: Bearer
curl -H "Authorization: Bearer $MUTE_KEY" https://api.mute.sh/v1/markets/overview

# 3. ?apikey= query param — for SSE/EventSource and WebSocket clients
#    that can't set headers
curl -N "https://api.mute.sh/v1/activity/stream?apikey=$MUTE_KEY"
```

All three are equivalent. Prefer the header forms for regular requests — query-string keys end up in logs more easily. The query param exists because the browser `EventSource` API and WebSocket handshakes can't set custom headers.

## No key? Anonymous free tier

Data endpoints work **without any key**: anonymous requests are metered **by IP** at the free tier (10 req/min, 1,000 req/month). Every response tells you how you're authenticated:

```
x-tier: free            ← anonymous or free-tier key
ratelimit-limit: 10
x-quota-limit: 1000
```

Authenticate to get your plan's limits instead. A revoked or malformed key is **not** silently downgraded — you get a `401`:

```json
{
  "statusCode": 401,
  "message": "The provided API key is invalid or revoked. Omit the key to use the free anonymous tier, or create one in the dashboard.",
  "path": "/v1/fills",
  "timestamp": "2026-07-03T12:26:41.878Z"
}
```

## What a key can and can't do

* **Data endpoints** (`/v1/markets/*`, `/v1/fills`, `/v1/portfolio/*`, streams, …) — any `mute_` key.
* **Enterprise-gated endpoints** (`/v1/sports/*`, `/v1/l1-votes/*`, webhook delivery history/replay) — keys on the Enterprise tier only; others get `403`.
* **Account management** (`/v1/keys`, `/v1/billing/*`, webhook subscription CRUD) — **dashboard session only**. These require a logged-in browser session on [app.mute.sh](https://app.mute.sh); API keys are deliberately not accepted, so a leaked data key can never rotate itself, mint new keys, or touch billing.

## Key hygiene

* Store keys in environment variables or a secret manager — never in client-side code. Anything shipped to a browser or mobile app is public.
* Rotate from the dashboard (`app.mute.sh` → API Keys → Rotate). Rotation invalidates the old key immediately.
* Use separate keys per environment (dev/staging/prod) so you can revoke one without breaking the others and can attribute usage per key in the dashboard.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mute-sh.gitbook.io/mute.sh/api/getting-started/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.