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

# Authentication

> How API keys, workspaces and credits fit together, and what happens when a key is wrong.

Every request carries your API key in the `X-API-Key` header. There is nothing else to set up.

```bash theme={null}
curl -X POST https://api.hydrafetch.com/v1/web/scrape \
  -H "X-API-Key: hf_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'
```

## Keys and workspaces

A key belongs to a **workspace**, and the workspace holds the **credits** your calls use. You can make as many keys as you like, for example one per environment or per service, and revoke any of them from the [dashboard](https://app.hydrafetch.com) without touching the others.

Keys start with `hf_`. Anyone who has your key can spend your credits.

> [!WARNING]
>
> Never put your API key in browser code, a public repository or a mobile app. Call Hydrafetch from your own server and keep the key in an environment variable or a secrets manager. The only key meant for the browser is a publishable key, used for [logos](https://docs.hydrafetch.com/endpoints/logo.md).

## When a key is refused

A refused request does no work and costs nothing. The error says why, in the same shape as every other [error](https://docs.hydrafetch.com/concepts/errors.md).

**No key, or a wrong or revoked key** answers `401`:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key. Agents: https://hydrafetch.com/auth.md"
  },
  "meta": { "requestId": "019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c" }
}
```

When the header is missing, the message says `Missing X-API-Key header` instead.

**An expired key** also answers `401`, with the date it expired: `This API key expired on Oct 1, 2026. Create a new key in the dashboard.`

**A key locked to IP addresses, called from somewhere else,** answers `403` and names the address the call came from:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key can't be used from 192.0.2.10. Add it to the key's allowed IPs in the dashboard."
  },
  "meta": { "requestId": "019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c" }
}
```

[API keys](https://docs.hydrafetch.com/help/api-keys.md) explains how to set an expiry and allowed addresses.

## Rotating a key

1. Create a new key in the dashboard.
2. Deploy it wherever the old one is used.
3. Revoke the old key. This takes effect at once.

Your credits, usage history and other keys are not affected.

> [card] [Next: Credits](https://docs.hydrafetch.com/concepts/credits.md)
>
> What each call costs, and why failed calls are free.


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