# webatla — API authentication

webatla exposes a public REST API at `https://webatla.com/api/v1` (file downloads under `https://webatla.com/api`).
Authentication uses **opaque Bearer API keys** (prefix `wbtl_`).

> Note: webatla is **not** an OAuth/OIDC provider and issues no OAuth tokens.
> There is no `/.well-known/openid-configuration` or `/.well-known/oauth-authorization-server` —
> authenticate with an API key as described below. (Google sign-in is for the web UI only.)

## Get a key

1. Create an account and sign in at `https://webatla.com/account`.
2. Open **API keys** at `https://webatla.com/account/api`.
3. Generate a key and copy the `wbtl_…` secret (it is shown only once).

## Call the API

Send the key as a Bearer token:

```
curl -H "Authorization: Bearer wbtl_xxx" https://webatla.com/api/v1/me
```

### Public (no key required)

- `GET /api/v1/datasets` — list published datasets (60 req/min per IP)
- `GET /api/v1/preview/{scope}/{key}` — free ~10k-row sample (30/min per IP)
- `GET /api/v1/sample/{scope}/{key}` — up to 20 real rows for one entity
- `GET /api/health` — service health (JSON)

### Authenticated (Bearer key)

- `GET /api/v1/me` — identify the key's user, id and scopes
- `GET /api/v1/me/orders` — your orders
- `GET /api/v1/me/downloads` — your download history
- `GET /api/download/{slug}` — download a purchased dataset export (JSONL, zstd)
- `GET /api/download/{slug}/{scope}/{key}` — one per-scope slice (single dimension per request)

## Scopes

Keys carry granular scopes, e.g. `me:read`, `orders:read`, `downloads:read`.
A request without the required scope gets `403`.

## Rate limits

200 req/min per key; 60 req/min per IP for session/public endpoints. On excess you get
`429` with a `Retry-After` header — back off and retry.

## Full spec

Machine-readable OpenAPI 3.1: `https://webatla.com/api/v1/openapi.json`