# auth.md

> How agents authenticate to Grabber: one API key, made by a person in the dashboard, sent as a Bearer token. There is no OAuth flow and no agent self-registration.

This applies to the REST API at https://api.grabber.sh and the MCP server at https://mcp.grabber.sh. The same key works for both.

## Get a key

1. Sign up at https://dashboard.grabber.sh/signup with an email address and verify it. The account starts with $1 of free credit, about 1,000 pages; no card is needed.
2. Create a key at https://dashboard.grabber.sh/keys. It starts with `gsh_` and is shown once, so store it as a secret, for example `GRABBER_API_KEY`.
3. Add credit at https://dashboard.grabber.sh/billing when it runs low, from $5, or turn on auto top-up.

An agent cannot create an account or a key by itself: a person does steps 1 and 2 and hands the key to the agent.

## Send the key

```http
GET /fetch?url=https%3A%2F%2Fexample.com%2F&formats=markdown HTTP/1.1
Host: api.grabber.sh
Authorization: Bearer gsh_your_api_key
```

The `Authorization` header is the only place a key is read. A key in the query string, such as `?key=gsh_...`, is refused as an unknown parameter with `400 invalid_query`.

For MCP, send the same header to https://mcp.grabber.sh.

## When it fails

- `401 invalid_api_key`, with `WWW-Authenticate: Bearer`: the key is missing, malformed, unknown or deleted. Nothing is charged.
- `402 insufficient_credits`: the balance is below the price of the request. The `hint` links to billing.
- `429 rate_limited`: more than 60 requests in a minute on this key. Wait the seconds in `Retry-After`.

## Keep keys safe

- Use one key per agent or app, so each can be deleted on its own. The dashboard shows usage and cost per key.
- Deleting a key in the dashboard stops it at once.
- Never put a key in a URL, a web page or a public repository.

## More

- Setup and usage: https://grabber.sh/skill.md
- Authentication docs: https://grabber.sh/docs/authentication.md
- Every page: https://grabber.sh/llms.txt