# Site key for a verified WordPress site

`POST https://api.astroway.info/v1/site-keys`

Issues a key to a site that proves it controls its domain: we fetch the proof from the site's REST route (`/wp-json/astroway/v1/verify?nonce=<proof_id>`, or `verify_url` for plain permalinks) and compare it with the one sent. The key is bound to the host, covers a free set of readings and shares 300 calls an hour with the other installs on the host (at most 5). One key per install (host + home path): a new key for the same install revokes the previous one. Server-side only. No API key needed.

Group: System. Auth: `X-Api-Key` header. Operation ID: `site-keys`.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `fields` | query | no | string | Comma-separated dotted paths, relative to `data`, to keep in the response. A path is applied to every element of an array, so `planets.name` means the name of each planet. Paths that match nothing come back in `_fields_unmatched`; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer. |
| `precision` | query | no | integer | Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `site_url` | string | yes | The site home URL, https only. A subdirectory multisite uses the network home. |
| `proof_id` | string | yes | UUID v4 the plugin generated for this attempt. |
| `proof` | string | yes | 32 random bytes, base64url. The site must serve the same value at its verify route. |
| `verify_url` | string | no | The verify REST route when /wp-json/ is not available, e.g. https://example.com/?rest_route=/astroway/v1/verify. Same host as site_url. |
| `plugin_version` | string | no |  |

```json
{
  "site_url": "https://example.com",
  "proof_id": "3f1c2a9e-8b7d-4c1e-9f3a-2b6d5e4c1a07",
  "proof": "q3v1Zk0yX2h8sR5tPwL9mN4bD7cF6gH1jK2lE0aS3uT",
  "plugin_version": "2.1.0"
}
```

## Responses

| Status | Meaning |
|---|---|
| 200 | Successful calculation |
| 400 | Validation error |
| 401 | Missing or invalid API key |

### Success fields, under `data`

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | string | no |  |
| `plan` | string | no |  |
| `domain` | string | no |  |
| `home_path` | string | no |  |
| `limits` | object | no |  |
| `limits.per_hour` | number | no |  |
| `endpoints` | string[] | no |  |
| `replaced_previous` | boolean | no |  |

## Example

```bash
curl -X POST https://api.astroway.info/v1/site-keys \
  -H "Content-Type: application/json" \
  -d '{ "site_url": "https://example.com", "proof_id": "3f1c2a9e-8b7d-4c1e-9f3a-2b6d5e4c1a07", "proof": "q3v1Zk0yX2h8sR5tPwL9mN4bD7cF6gH1jK2lE0aS3uT", "plugin_version": "2.1.0" }'
```

---

Rendered from https://api.astroway.info/v1/openapi.json. HTML page: https://api.astroway.info/docs/api/operations/site-keys/