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:

{ "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.

Connecting an account

When the site owner wants to run on their own plan, the plugin moves the site onto the account’s key in one click.

1. The plugin opens in the admin’s browser https://api.astroway.info/dashboard/connect?site=<home_url>&return=<admin_url>&state=<16-128 characters>&source=wp_plugin. return must be on the same host as site, over https.
2. The admin signs in or registers and picks a key for the site, or creates a new one. A key already bound to another domain moves only after a separate confirmation.
3. The browser returns to return with code and the same state. Cancelling returns error=access_denied.
4. The site’s server exchanges the code, sending its site key in X-Api-Key:

POST /v1/site-keys/connect/exchange
{ "code": "<43 characters>", "site_url": "https://example.com" }

Response: { "key": "aw_live_…", "plan": "free", "domain": "example.com", "account": "j***@example.com" }. The code lives 5 minutes. Exchanging the same code with the same site key within 10 minutes returns the same answer. The site key stops working 24 hours after the exchange.

Errors: 400 INVALID_CODE, 410 CODE_EXPIRED, 403 SITE_MISMATCH.