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

# Authentication

> Authenticate every Blockworks API request with an API key sent in the X-Blockworks-API-Key header.

Blockworks authenticates requests with an API key sent in a request header. There is no
OAuth flow, no token exchange, and no session state. Every request carries the key.

One key covers every product. The same key authenticates the [Data API](/getting-started/data-api),
[Monitoring](/api-reference/monitoring/overview), the
[Token Unlocks API](/api-reference/token-unlocks/overview), and the
[MCP Server](/mcp/overview). Datashare access is granted to your warehouse account rather
than by key. See [Datashares](/datashare/overview).

## Get an API key

Create and manage keys at [app.blockworks.com/account/api](https://app.blockworks.com/account/api).
Keys are shown once at creation, so store yours in a secret manager or environment variable.

## Using your key

Pass the key in the `X-Blockworks-API-Key` header on every request to `https://api.blockworks.com`:

```bash theme={null}
curl 'https://api.blockworks.com/query/ping' \
  --header "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"
```

For a full first request in curl, Python, and JavaScript, see the
[Data API quickstart](/getting-started/quickstart) or the
[Monitoring quickstart](/api-reference/monitoring/quickstart).

<Note>
  The header name is `X-Blockworks-API-Key`. Header names are case-insensitive, so
  `x-blockworks-api-key` works identically. The legacy `x-messari-api-key` header is still
  accepted for existing integrations; new code should send `X-Blockworks-API-Key`.
</Note>

## Access tiers

Not every dataset requires the same level of access. Each model in the catalog declares an access
tier, and the API enforces it per request:

| Tier         | Who can query it                                                               | Without the required access                                                             |
| ------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `public`     | Anyone, including unauthenticated requests.                                    | never refused (an invalid key is still `403 Forbidden`)                                 |
| `unpaid`     | Any request that carries a valid API key, on any plan.                         | `401 this model requires authentication`                                                |
| `paid`       | A valid key on a paid plan (Lite, Pro or Enterprise).                          | `401` without a key, `403 this model requires a paid subscription` with a free-plan key |
| `permissive` | A valid key holding the model's specific permission (`access.permissionSlug`). | `401` without a key, `403` otherwise                                                    |

Models restricted to internal users do not appear in the public catalog or in this reference.

Paid is the default tier of the reference, so reference pages only call out the exceptions (public
models and models that need a specific permission). You can read the tier of any model from `access.tier` in the
[catalog endpoints](/getting-started/concepts/catalog). See [Errors](/getting-started/errors) for
the exact messages.

## Rate limits

The Data API itself enforces no rate limit and sends no `RateLimit-*` or `Retry-After` headers.
Responses are cached for 30 minutes (`Cache-Control: max-age=1800`), so repeating an identical
request within that window is served from cache. Keep concurrency reasonable and prefer `selections`
and narrow time windows over large repeated pulls.

<Warning>
  **Keep your key secret.** Never commit it to version control, embed it in a client-side bundle, or
  paste it into a shared document or support ticket. Requests made with your key count against your
  account.
</Warning>

## Handling keys safely

<CardGroup cols={3}>
  <Card title="Server-side only" icon="server">
    Call the API from your backend. A key shipped to a browser or mobile app is a public key.
  </Card>

  <Card title="Environment variables" icon="key">
    Load the key from the environment or a secrets manager rather than hardcoding it.
  </Card>

  <Card title="Rotate regularly" icon="rotate">
    Regenerate your key periodically, and immediately if you suspect it has leaked.
  </Card>
</CardGroup>

## Verify your setup

`/query/ping` is a lightweight endpoint for confirming your client is wired up correctly. The
request above returns:

```json theme={null}
{
  "error": null,
  "data": { "message": "pong" }
}
```