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

> ## Agent Instructions
> The Zenrows HTTP API serves Fetch and Extract (extract=auto) at https://api.zenrows.com/v1/, Crawl at https://api.zenrows.com/v1/crawls, and Batch at https://async.api.zenrows.com/v1. Fetch, Extract, Crawl and Batch are described in OpenAPI 3.1 at https://www.zenrows.com/openapi.json and listed in the RFC 9727 API catalog at https://www.zenrows.com/.well-known/api-catalog. Every endpoint also has its own page under /api-reference with its schema. Use the spec for exact parameter names and types. Crawl's endpoints, parameters and errors are also at https://docs.zenrows.com/crawl/endpoints.md. To call Zenrows from an agent, connect the MCP server at https://mcp.zenrows.com/mcp. To search these docs from an agent, connect the docs MCP server at https://docs.zenrows.com/mcp. Agent skills for Zenrows are published at https://github.com/ZenRows/cli and install with `npx skills add ZenRows/cli`.

# Zenrows API Authentication

> How to authenticate Zenrows API requests: where to find your API key, how to send it to Fetch, Extract, Batch and Crawl, how the Zenrows MCP server signs in with OAuth, and how agent-created accounts are claimed.

Every Zenrows API request is authenticated with your account's API key. The key is the credential itself: there is no separate token exchange for the Fetch (formerly, Universal Scraper API), Extract, Batch or Crawl APIs.

## Get your API key

Create a free account, then copy your key from the API keys page (**Settings** > **API keys**). An account can have up to 10 API keys, each with its own credit caps. See [API Keys and Credit Caps](https://docs.zenrows.com/first-steps/api-key-credit-caps.md).

[Sign up free](https://app.zenrows.com/register?p=free)
[Get your API key](https://app.zenrows.com/settings/api-keys)

You can also start with no account at all: the local MCP server creates a Free account and key for you on its first tool call, the CLI the first time it runs without one, and any agent can do the same with one request. See [Agent signup and unclaimed accounts](#agent-signup-and-unclaimed-accounts).

> [!TIP]
>
> Store your key in an environment variable or a secrets manager, and never commit it or share it publicly.

## How to send the key

| Surface | Base URL | How the key is sent |
| - | - | - |
| [Fetch](https://docs.zenrows.com/fetch/api-reference.md), including `extract=auto` | `https://api.zenrows.com/v1/` | `apikey` query parameter |
| [Extract endpoints](https://docs.zenrows.com/extract/endpoints.md) | `https://api.zenrows.com/v1/extract/` | `apikey` query parameter or `X-API-Key` header |
| [Crawl](https://docs.zenrows.com/crawl/endpoints.md) | `https://api.zenrows.com/v1/crawls` | `X-API-Key` header or `apikey` query parameter |
| [Batch](https://docs.zenrows.com/batch/developer-guide-restapi.md) | `https://async.api.zenrows.com/v1` | `X-API-Key` header only, never in the URL |
| [Plan usage](https://docs.zenrows.com/fetch/features/other.md#plan-usage) | `https://api.zenrows.com/v1/subscriptions/self/details` | `X-API-Key` header |
| [MCP server](https://docs.zenrows.com/mcp/overview.md) | `https://mcp.zenrows.com/mcp` | OAuth 2.1 sign-in, or `Authorization: Bearer YOUR_ZENROWS_API_KEY` |

A Fetch request with the key in the query string:

```bash cURL theme={"theme":"css-variables"}
curl "https://api.zenrows.com/v1/?apikey=YOUR_ZENROWS_API_KEY&url=https%3A%2F%2Fhttpbin.io%2Fanything"
```

A Batch request with the key in the header:

```bash cURL theme={"theme":"css-variables"}
curl "https://async.api.zenrows.com/v1/jobs" \
  -H "X-API-Key: YOUR_ZENROWS_API_KEY"
```

The [SDKs](https://docs.zenrows.com/sdk/overview.md) and the [CLI](https://docs.zenrows.com/cli/introduction.md) take the same key and send it for you.

## MCP server: OAuth 2.1

The remote Zenrows MCP server accepts OAuth 2.1 with PKCE (S256), or your API key as a Bearer token. With OAuth, the user signs in at `app.zenrows.com` and approves access, and the access token issued is the account's API key, so every tool runs with that key's permissions. Discovery, dynamic client registration and the single `api` scope are described in [MCP authentication and permissions](https://docs.zenrows.com/mcp/tool-reference.md#authentication-and-permissions).

## Agent signup and unclaimed accounts

An agent with no human present can create its own Zenrows account and API key. The account is on the Free plan and stays **unclaimed** until a person claims it. An unclaimed account gets 5,000 credits for its first billing period only, which starts at signup. It is not renewed after that: requests answer `402 AUTH005` until a person claims the account. A claimed account renews every billing period like any Free account.

Three things create one:

* The [local MCP server](https://docs.zenrows.com/mcp/overview.md#start-without-an-api-key) (`npx -y @zenrows/mcp`), on its first tool call with no `ZENROWS_API_KEY`. A refused signup returns a tool error saying when to retry, and the server keeps running.
* The [CLI](https://docs.zenrows.com/cli/introduction.md), on its first cloud command with no key configured.
* A direct request: `POST https://app.zenrows.com/api/agent/signup` with an empty body. The `201` response carries `apiKey`, `accountId` and `claimUrl`.

### Answer the signup question

Signup may first ask one short question that the agent answers itself, as a light check that an agent is in the loop: which word is in a category (a bird, a fruit, a tool) or which word does not belong (the answer is always a word from the question). The direct request then returns `428` with the error `challenge_required`:

```json JSON theme={"theme":"css-variables"}
{
  "message": "To create a Zenrows account, answer: which of norway, walrus, pear is a country? Run: curl -X POST https://app.zenrows.com/api/agent/signup -d c=f4261db6 -d a=ANSWER",
  "error": "challenge_required",
  "challenge": { "id": "f4261db6", "prompt": "which of norway, walrus, pear is a country?", "expires_in": 600 }
}
```

Answer with the same `POST`, from the same network, within `expires_in` seconds, as JSON (`{"challenge_id": "f4261db6", "answer": "norway"}`) or as a form (`-d c=f4261db6 -d a=norway`). Case and punctuation don't matter. A right answer returns the `201` above. A wrong or expired answer returns another `428` with a new question, and each question can be answered once. After too many questions or wrong answers from this network, signup returns `429` with the error `challenge_locked` and `Retry-After: 3600`: wait an hour or use an existing API key.

The tools pass the question to the agent the same way:

* **Local MCP server:** the tool call that triggers signup returns the question. The agent answers with the `account_signup_answer` tool (`{"answer": "..."}`), then retries its tool call.
* **CLI:** a command that needs a key prints `[SIGNUP_CHALLENGE]` with the question (with `--json`, `error.challenge` carries `id`, `question` and `expires_at`). The agent runs `zenrows signup --answer "<answer>"`, then re-runs its command.

The remote MCP server never creates accounts this way. Its OAuth sign-in lets a person log in or create a regular Free account instead. A headless agent that calls a remote tool without a key gets a `401` whose body names this signup endpoint in an `agent_signup` field, and the server's `/.well-known/oauth-authorization-server` metadata lists it in an `agent_auth` block. The agent signs up there, then sends the returned `apiKey` as its Bearer token.

Each network can create 3 agent accounts in 24 hours (IPv6 addresses count per `/64`). A fourth request returns `429` with the error `rate_limited` and a `Retry-After` header in seconds. Wait that long, or use a key you already have. Never sign up again to get past spent credits or a key's credit cap: the new account starts from zero and the old one keeps its usage.

### Claim an account

Claiming gives the account an owner and an email. The same API key keeps working, and the account's past usage and its plan stay as they were. Claiming adds no credits to a period that is still running. If the first period has already ended, claiming starts a new billing period from the moment of the claim, with the plan's full allowance.

1. The agent hands its claim link (`https://app.zenrows.com/claim/...`) to a person.
2. The person opens it in a browser and proves an email there: **Continue with Google**, **Continue with GitHub**, or a 6-digit code sent to the email they type, after which they set a password.
3. If that email already has a Zenrows account, the page says so. Accounts are never merged: give the agent the API key from the existing account instead.

Claim links expire after 30 days and work once. To get a new one, send the account's key:

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://app.zenrows.com/api/agent/claim" \
  -H "X-API-Key: YOUR_ZENROWS_API_KEY"
```

The response holds a new `claimUrl` and its `expiresAt`, and the previous link stops working. You can ask for 5 links per hour per key. An account that is already claimed answers `409` with `already_claimed`. With the CLI, `zenrows account claim` checks whether the account is claimed, asks for a fresh link when the stored one is missing or 25 days old or more, and opens it. On a claimed account it says so instead.

The local MCP server and the CLI keep their stored link current on their own: before they show a claim link, they ask for a fresh one when the stored link is missing or 25 days old or more, and once the account is claimed they stop showing claim links.

To check whether a person has claimed the account, send the same key to `GET https://app.zenrows.com/api/agent/account`. The `claimed` field is `true` once they have.

> [!WARNING]
>
> Treat a claim link like a password. Whoever opens it first can claim the account and its API key. Send it only to the person who should own the account.

### Turn auto-signup off

* **Local MCP server:** set `ZENROWS_AUTO_SIGNUP` to `false`. The server then needs `ZENROWS_API_KEY`.
* **CLI:** pass `--no-signup` on a command, or set `auto_signup` to `false` in `.zenrows/policy.json`.

### In CI

A CI runner starts clean, so a tool that signs up on its own creates a new account on every run, and the fourth run from the same network within 24 hours is refused. Store your API key as a CI secret and pass it as `ZENROWS_API_KEY`, or keep the stored key between runs: `~/.zenrows` (or `ZENROWS_HOME`) for the local MCP server, the project's `.zenrows/` folder for the CLI. Turn auto-signup off in CI so a missing secret never creates an account: the CLI then fails the job, and the local MCP server keeps running but returns an error from every tool call until a key is set.

## In the OpenAPI spec

The [Zenrows OpenAPI spec](https://www.zenrows.com/openapi.json) declares two API key security schemes: `apiKeyQuery` (the `apikey` query parameter, used by Fetch and Extract) and `apiKeyHeader` (the `X-API-Key` header, used by Batch). A generated client reads them from there.

## Authentication errors

A missing or invalid key returns `401 Unauthorized`. The `code` in the body depends on the surface:

* **Fetch, including `extract=auto`:** `AUTH001` (key missing), `AUTH002` (key malformed) or `AUTH003` (key not found). Each one, and the fix for it, is listed under [401 Unauthorized](https://docs.zenrows.com/api-error-codes.md#401).
* **Batch and the Extract prepared-domains endpoints:** `unauthenticated`. See [Batch and Extract error codes](https://docs.zenrows.com/api-error-codes.md#unauthenticated). Batch answers a valid key whose subscription needs a billing action with [`subscription_inactive`](https://docs.zenrows.com/api-error-codes#subscription_inactive), also `401`.


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