# SuperScraper auth for agents

How an agent gets an API key, how it authenticates, and where to go next.

Base URL: `https://api.superscraper.dev`

## 1. Get a key

An agent can mint its own free-tier key. No key, human sign-in, or approval step is
needed for this call.

```
POST https://api.superscraper.dev/v1/keys/provision
Content-Type: application/json

{ "label": "research-agent", "email": "owner@example.com" }
```

Both body fields are optional. `label` names the key and account (default `agent`,
up to 60 characters). `email` is an optional contact address.

Response `201`:

```json
{
  "apiKey": "ss_live_<shown once>",
  "tenantId": "<uuid>",
  "tier": "free",
  "credits": { "scrape": 1000, "enrich": 1000, "kyb": 0, "state": "ok", "period": "<current period>" },
  "quota": { "pages": 1000, "extractions": 50 },
  "creditsGranted": ["..."],
  "note": "Free tier. For more credits, upgrade to a paid plan with POST /v1/billing/checkout (plans and prices: GET /v1/pricing)."
}
```

- The key is returned once. Store it; it cannot be read back later.
- `credits.state` says whether the free credits were applied: `ok`, `grant_pending`,
  `grant_failed`, or `reconciling`. `GET /v1/credits` and `GET /v1/usage` report the
  same field.
- Numbers above are the current free plan. `GET /v1/pricing` is the live catalog.

Other responses:

| Status | Meaning |
| --- | --- |
| 403 | Self-serve provisioning is turned off. |
| 429 | Too many provisioning requests from this client or overall. Wait and retry. |
| 503 | Provisioning is unavailable, or the free credit grant could not be recorded. No key was created. Retry shortly. |
| 500 | Account or key creation failed. |

## 2. Authenticate

Send the key on every `/v1/*` call, in either header:

```
x-api-key: ss_live_<your_key>
Authorization: Bearer ss_live_<your_key>
```

A missing, invalid, or revoked key returns `401`. A request the credit balance or monthly quota
cannot cover returns `402`, checked before any work runs. Free keys are limited to
10 requests per minute; a `429` carries `Retry-After`.

Public routes that need no key: `POST /v1/keys/provision`, `GET /v1/pricing`,
`GET /v1/status`, `GET /health`, `GET /openapi.json`.

## 3. Where a human comes in

Nothing on the free tier waits for a human. A person is needed only to pay:

- `POST /v1/billing/checkout` (with the key) returns a checkout session for a paid
  plan. A human completes the payment.
- Keys can also be created and managed by a human in the dashboard at
  https://app.superscraper.dev.

Never paste a key into a public page, repository, or prompt log.

## 4. Next steps

- Condensed API index: https://superscraper.dev/llms.txt
- Full reference: https://superscraper.dev/llms-full.txt
- Agent onboarding skill: https://api.superscraper.dev/agent-onboarding/SKILL.md
- Docs: https://docs.superscraper.dev
- MCP status: https://superscraper.dev/mcp (hosted MCP is not available; use the REST API)
- Playground, no key: https://superscraper.dev/playground