# Stophy auth

Search, read, and act on the web. Every call takes an API key, sent as `Authorization: Bearer <key>`.

## Get a key

Your person approves every new account. It starts with $2 of free balance. Pick one:

- **Dashboard:** your person signs up at https://stophy.dev/signup, creates a key at https://stophy.dev/app/api-keys and sets it as `STOPHY_API_KEY`.
- **CLI:** run `stophy login --browser`. Your person approves in the browser, and the CLI saves the key.
- **Agent signup:** `POST https://api.stophy.dev/v1/signup` needs no key and returns a `claimUrl` and a `code`. Give your person the `claimUrl`. After they approve, `POST https://api.stophy.dev/v1/signup/poll` with the `code` returns the key.

Each way, with the answers it returns: https://docs.stophy.dev/get-credentials

## Send the key

The CLI and the SDKs read `STOPHY_API_KEY`, which wins over a key that `stophy login` saved. `stophy doctor` shows where the CLI saved it.

```bash
curl -X POST https://api.stophy.dev/v1/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"bun runtime"}'
```

For MCP, https://mcp.stophy.dev/mcp signs in through the browser or takes the key as a bearer header. Setup for each client: https://docs.stophy.dev/install-mcp

## Without a key

Search, Web Scrape, Web Parse and Web Map also answer without a key, and so do the parsers marked `keyless: true` at https://api.stophy.dev/v1/parsers, with 10 calls a minute and 50 a day for each IP address, first page only. https://api.stophy.dev/mcp serves them over MCP. Every other call needs a key.

## When a call is refused

An error is `{ "success": false, "error": "<what to do next>", "code": "<code>" }`.

- `apiKeyRequired` (401): the call needs a key. `signup` names the call that gets one.
- `freeLimit` (429): the free calls for this IP address are used up. Wait `retryAfterSeconds`, or send a key.
- `rateLimited` (429): you went over 100 requests a minute per endpoint before your first top-up, 600 after. Wait `retryAfterSeconds`.
- `insufficientCredits` (402): the balance is below the call's price, and nothing was charged. Your person tops up at https://stophy.dev/billing.

Every code: https://docs.stophy.dev/api-reference/errors

## Keep the key secret

Keep the key in `STOPHY_API_KEY` or your client's secret settings. Never put it in chat, a command line, code or logs. If it leaks, your person revokes it at https://stophy.dev/app/api-keys.
