# WordPress site keys

The AstroWay WordPress plugin gets a key on its own, without a signup: the site shows a proof on its REST route, we check it and issue a key bound to that site.

## How verification works

1. The plugin generates `proof_id` (UUID v4) and `proof` (32 random bytes, base64url, 43 characters) and keeps them for 10 minutes.
2. The site answers `GET <home_url>/wp-json/astroway/v1/verify?nonce=<proof_id>` with `Content-Type: application/json` and the body `{"proof":"<proof>"}`.
3. The plugin sends `POST /v1/site-keys`:

```json
{ "site_url": "https://example.com", "proof_id": "3f1c2a9e-8b7d-4c1e-9f3a-2b6d5e4c1a07", "proof": "<43 characters>" }
```

`site_url` is exactly `home_url()`, with no `?` and no `#`. On plain permalinks pass `verify_url` with `?rest_route=/astroway/v1/verify`: it is accepted only on the same site and only as that route.

## What the key gives

- for the site's server: a request from a browser (with an `Origin` header) gets 403, and every call must name the site in `X-AstroWay-Site-URL`. The binding rests on that header, so keep the key secret, and if it leaks, issue a new one: the previous one is revoked;
- a set of free readings, 300 calls an hour per site, no credits; dated horoscopes are accepted only near today's date;
- one key per install (host and home path), up to 5 installs per host sharing the hour.

Errors: `400 INVALID_SITE_URL`, `422 SITE_VERIFICATION_FAILED` with `details.reason`, `429 SITE_KEY_RATE_LIMIT` with `retry_after`.