# Limited API keys

Every workspace has a **main key** with full access (the one from `POST /v1/sandbox` or the panel). You can add **limited keys** that can only do what their scopes say, for example a read-only key for a dashboard. Existing keys keep full access.

## Scopes

| Scope | Allows |
| --- | --- |
| `posts:read` | `GET /v1/posts`, `GET /v1/posts/{id}`, `GET /v1/analytics/overview`, reading the queue. |
| `posts:write` | `POST /v1/posts`, `POST /v1/posts/bulk`, `PATCH` and `DELETE /v1/posts/{id}`. |
| `accounts:read` | `GET /v1/accounts`. |
| `accounts:write` | `POST /v1/connect`, `DELETE /v1/accounts/{id}`. |
| `media:write` | `POST /v1/media`, `POST /v1/media/upload`. |
| `webhooks:write` | `GET`, `PUT` and `DELETE /v1/webhooks`. |
| `queue:write` | `PUT /v1/queue` (and reading it). |

`GET /v1/me` works with any key. A call without the scope it needs answers `403 insufficient_scope` with `details.required_scope`.

## Create, list, revoke

```
curl -X POST https://wyroapi.com/v1/keys -H "Authorization: Bearer $WYRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "metrics dashboard", "scopes": ["posts:read", "accounts:read"]}'
```

- `POST https://wyroapi.com/v1/keys {"scopes": [...], "name"?}`: returns `api_key` **once** (and `mcp_url`). Only a full-access key can create keys (`required_scope: "full_access"` otherwise). Takes an `Idempotency-Key` (a replay returns `api_key` as null).
- `GET https://wyroapi.com/v1/keys`: active keys with `key_hint`, `scopes` (`null` = full access), `primary`, `created_at`, `last_used_at`.
- `DELETE https://wyroapi.com/v1/keys/{id}`: revokes a limited key at once. Neither the key making the call nor the main key can be revoked here (`key_not_revocable`); the main key is rotated from the panel.

Up to 25 active limited keys per workspace. A limited key follows the main key: same mode (test, trial, plan) and end date. Creating one never changes the main key, so the panel, the OAuth connector and partners keep working as before.

## Partners

```
curl -X POST https://wyroapi.com/v1/partner/workspaces/ws_abc123/keys \
  -H "Authorization: Bearer $WYRO_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["posts:read"]}'
```

`POST /v1/partner/workspaces/{id}/keys` gives one of your clients a limited key (e.g. read-only for their own dashboard); `GET` on the same path lists that client's keys. Acting for the client with the partner token and `X-Wyro-External-Id` keeps full access.

## In the panel

Key and API → **Keys of this account**: the main key and the limited ones with their permissions, **Create limited key** and **Revoke**.
