# AlterLab auth.md: how an agent gets access

AlterLab is a web scraping API. This page describes every way an AI agent can obtain credentials, on its own or on a user's behalf. Machine-readable discovery: https://alterlab.io/.well-known/api-catalog

## 1. Sign up (a human does this once)

- Create an account at https://alterlab.io/signup.
- New accounts get a free balance: Up to 5,000 free requests. No credit card is required.
- Create an API key in the dashboard: https://alterlab.io/dashboard/api-keys.

## 2. API keys

Send the key on every request, in either header:

```
X-API-Key: <your key>
Authorization: Bearer <your key>
```

REST API base URL: https://api.alterlab.io. OpenAPI description: https://alterlab.io/openapi.json. Documentation: https://alterlab.io/docs.

## 3. OAuth 2.0 for MCP clients

The hosted MCP server is https://mcp.alterlab.io/mcp (Streamable HTTP). It accepts an OAuth access token or an API key (same two headers as above).

- Authorization server metadata (RFC 8414): https://alterlab.io/.well-known/oauth-authorization-server
- Protected resource metadata (RFC 9728): https://mcp.alterlab.io/.well-known/oauth-protected-resource
- Dynamic client registration (RFC 7591): POST https://api.alterlab.io/api/v1/oauth/register
- PKCE with the `S256` method is required.
- Authorization endpoint: https://api.alterlab.io/api/v1/oauth/authorize
- Token endpoint: https://api.alterlab.io/api/v1/oauth/token

Supported scopes:

- `account:read`
- `billing:read`
- `scrape`

An unauthenticated request to the MCP endpoint returns `401` with a `WWW-Authenticate: Bearer resource_metadata="..."` challenge that points at the protected resource metadata. MCP clients follow it automatically; the user approves access in the browser.

## 4. Zero-signup trial token

An agent can start without any account:

```
curl -X POST https://api.alterlab.io/api/v1/agent/trial
```

The response contains a one-time `key` (prefix `sk_trial_`), its `scopes`, `expires_at` and `request_cap`. Use it like any API key. Limits: 50 requests per key, expiring after 24 hours; issuance is rate limited per IP. The response also carries a `claim_url` (valid 7 days). Every later response authenticated by the trial key repeats it in the `X-AlterLab-Claim-URL` header, and so do the trial-cap and trial-expired errors. Give that link to your human. They sign in or sign up and open it, and the same key becomes a normal key on their account: the `trial` scope and expiry are removed and it keeps working with no reconfiguration. New accounts get a free balance: Up to 5,000 free requests. The claim link is signed and separate from the key, so showing it to a human never exposes the key. A hosted MCP session using a trial key gets the link appended to its tool results.

If you cannot use OAuth with the MCP server, the trial endpoint above is your path: the `401` challenge from the MCP endpoint points to it.

## 4b. Keyless pay-per-request (x402)

When enabled, an agent with no account and no key can pay per request in USDC over HTTP 402 (x402 v2) on `POST https://api.alterlab.io/api/v1/scrape`. Send the request with no credentials. The `402` response carries the quote in the `PAYMENT-REQUIRED` header (base64 JSON, `exact` scheme). Sign it and retry with `PAYMENT-SIGNATURE`. The payment is settled only after a successful scrape; the receipt comes back in `PAYMENT-RESPONSE`. Requests that carry an API key or bearer token are never quoted. Sync `auto`, `html` and `js` GET scrapes only; wallets on sanctions lists are refused.

## 4c. Billing contract for budgeting (machine-readable)

- Pay only on success: a failed scrape is never charged. Credits are billed only when the job succeeds.
- Pre-call quote: call the `alterlab_estimate_cost` MCP tool (or `POST https://api.alterlab.io/api/v1/scrape/estimate`) to get the cost before submitting.
- Failed responses carry a `next_action` object: `reason_class`, `retry_with` (`{tier, mode}` or null), `estimated_cost_microcents`, `retry_after_s` and `action_url`.
- Live reliability by anti-bot class and tier: https://alterlab.io/.well-known/alterlab-reliability.json

## 4d. MPP prepaid sessions

Agents that speak the Machine Payments Protocol (https://mpp.dev) can top up a prepaid session with a Stripe Shared Payment Token: `POST https://api.alterlab.io/api/v1/scrape` with no credentials returns a `402` with a `WWW-Authenticate: Payment` challenge for a $0.50 top-up. Retry with `Authorization: Payment <credential>`; the response carries `X-AlterLab-Session` and a `Payment-Receipt`. Send `X-AlterLab-Session` on later scrapes: each successful scrape is deducted in sub-cent amounts, failed scrapes cost nothing.

## 5. Agent-initiated signup (human approval)

An agent can request an account for its human without any pre-existing key:

1. `POST https://api.alterlab.io/api/v1/agent/signup` with `{email, agent_name, agent_url?, requested_scopes}` returns `{signup_id, verification_url, user_code, poll_interval, expires_in: 900}`.
2. The human gets an email naming the agent, its permissions and the spend cap, and approves at `verification_url` (or with the `user_code`). No account, key or balance exists before approval, and no extra free credit is granted.
3. Poll `GET https://api.alterlab.io/api/v1/agent/signup/{signup_id}` every `poll_interval` seconds. After approval it returns a scoped, spend-capped ($5 default) API key once, labeled "Agent: <agent_name>" and revocable from the dashboard.

Optionally sign the signup request with Web Bot Auth (HTTP Message Signatures, `Signature-Agent`) for a higher rate tier. MCP: the `alterlab_create_account` tool.