# auth.md — how an agent authenticates with RobotsDataset

Audience: autonomous agents and their developers calling `https://robotsdataset.com/v1` (REST) or `https://robotsdataset.com/mcp` (MCP, streamable HTTP). Everything below is machine-actionable; nothing here needs a human in a browser.

## Do you even need a credential?

No, for discovery. The catalog, schemas, `/status`, `/facets`, every `llms.txt`, `/examples`, `/samples` and `/changelog` are free and unauthenticated, plus 20–50 public-field record previews per day per IP (the number is per dataset). Full records, search results, `/stats`, `/timeseries`, `/compare` and history are priced per call.

## Registration

- **Endpoint:** `POST https://robotsdataset.com/v1/keys`
- **Body:** `{"email": "you@example.com"}` (JSON)
- **Response 201:** `{"key": "<secret>", …}` with a €0.50 welcome credit. The key is shown once and never again; store it before the next call.
- **Limit:** one key per e-mail address; a second request for the same address returns 409.

```bash
curl -s -X POST https://robotsdataset.com/v1/keys -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'
```

## Supported methods

### 1. Bearer API key (prepaid credits)

- `Authorization: Bearer <key>` on every request. `X-API-Key: <key>` is accepted as an alternative header.
- Balance and ledger: `GET https://robotsdataset.com/v1/keys/me` with the same header.
- Each call is charged from the credit balance; the price of every endpoint is in `https://robotsdataset.com/.well-known/x402.json` and on each dataset page.
- Keys do not expire and carry no scopes: one key, one balance, the whole read-only surface.

### 2. x402 (pay per call, no account)

- Call without a credential, get `402` with a `PAYMENT-REQUIRED` header, pay, repeat the request with `PAYMENT-SIGNATURE`.
- Terms, accepted stablecoins and the facilitator: `https://robotsdataset.com/.well-known/x402.json` (network `base`).
- This is the rail an agent with a wallet should use; there is nothing to register.

### 3. Anonymous

- No header at all: free endpoints plus the daily preview quota above. Exceeding it returns `402`, not `401` — the body says the price and how to pay.

## Using the credential

```bash
curl -s 'https://robotsdataset.com/v1/{dataset}/entities?limit=5&fields=name' \
  -H 'Authorization: Bearer <key>'
```

- Send the credential on every request; there is no session, cookie or token exchange.
- `401` means the key is unknown, `402` means it is valid but the call must be paid for, `429` means slow down (`Retry-After` and `X-RateLimit-*` are on the response).
- Never put the key in a query string in production; `?api_key=` exists only for browser testing.

### 4. OAuth 2.1 (for MCP clients and anything that will not paste a secret)

- Protected resource metadata: `https://robotsdataset.com/.well-known/oauth-protected-resource` (RFC 9728) → authorization server: `https://robotsdataset.com/.well-known/oauth-authorization-server` (RFC 8414).
- Register yourself: `POST https://robotsdataset.com/oauth/register` (RFC 7591). No credential needed for a public client; send an API key to also get `client_credentials`.
- Then authorization code with PKCE (S256 required). The person approving in the browser signs in with their own key, and consent means the client may spend from that key.
- Access tokens are ES256 JWTs valid for one hour, verified against `https://robotsdataset.com/oauth/jwks.json`; refresh tokens are revocable at `https://robotsdataset.com/oauth/revoke`.
- Scope: `read`. A token is presented exactly like a key: `Authorization: Bearer <token>`.
- A `401` carries `WWW-Authenticate` with `resource_metadata` pointing back at the document above, so a client that guessed wrong can find the right door.
- There is no OpenID Connect: the subject of a token is an API key, not a person, so no `id_token` and no `/.well-known/openid-configuration`.

## More

- Rules, workflow and URL patterns for agents: `https://robotsdataset.com/llms.txt`
- API catalog (RFC 9727): `https://robotsdataset.com/.well-known/api-catalog`
- OAuth metadata: `https://robotsdataset.com/.well-known/oauth-protected-resource` · `https://robotsdataset.com/oauth/jwks.json`
- Human documentation: `https://robotsdataset.com/developers` · pricing: `https://robotsdataset.com/pricing`
- Licence and what you may do with the data: `https://robotsdataset.com/legal/license`
- Contact: webmaster@robotsdataset.com