Skip to main content
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. 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.
Store your key in an environment variable or a secrets manager, and never commit it or share it publicly.

How to send the key

A Fetch request with the key in the query string:
cURL
A Batch request with the key in the header:
cURL
The SDKs and the CLI 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.

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 (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, 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
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:
cURL
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.
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 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.
  • Batch and the Extract prepared-domains endpoints: unauthenticated. See Batch and Extract error codes. Batch answers a valid key whose subscription needs a billing action with subscription_inactive, also 401.