# Chaves limitadas

Todo espaço tem uma **chave principal** com acesso completo (a de `POST /v1/sandbox` ou do painel). Você pode somar **chaves limitadas** que só fazem o que os scopes dizem, por exemplo uma chave só de leitura para um painel. As chaves que já existem mantêm acesso completo.

## Scopes

| Scope | Permite |
| --- | --- |
| `posts:read` | `GET /v1/posts`, `GET /v1/posts/{id}`, `GET /v1/analytics/overview`, ler a fila. |
| `posts:write` | `POST /v1/posts`, `POST /v1/posts/bulk`, `PATCH` e `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` e `DELETE /v1/webhooks`. |
| `queue:write` | `PUT /v1/queue` (e lê-la). |

`GET /v1/me` funciona com qualquer chave. Uma chamada sem o scope que precisa responde `403 insufficient_scope` com `details.required_scope`.

## Criar, listar, revogar

```
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"?}`: devolve `api_key` **uma vez** (e `mcp_url`). Só uma chave com acesso completo cria chaves (senão, `required_scope: "full_access"`). Aceita `Idempotency-Key` (a resposta repetida traz `api_key` como null).
- `GET https://wyroapi.com/v1/keys`: chaves ativas com `key_hint`, `scopes` (`null` = acesso completo), `primary`, `created_at`, `last_used_at`.
- `DELETE https://wyroapi.com/v1/keys/{id}`: revoga uma chave limitada na hora. Nem a chave que faz a chamada nem a principal podem ser revogadas aqui (`key_not_revocable`); a principal é girada pelo painel.

Até 25 chaves limitadas ativas por espaço. Uma chave limitada segue a principal: mesmo modo (teste, período de teste, plano) e mesma data de fim. Criar uma nunca muda a principal, então o painel, o conector OAuth e os parceiros continuam funcionando igual.

## Parceiros

```
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` dá a um cliente seu uma chave limitada (por exemplo só leitura para o painel dele); `GET` no mesmo caminho lista as chaves desse cliente. Atuar pelo cliente com o token de parceiro e `X-Wyro-External-Id` mantém acesso completo.

## No painel

Chave e API → **Chaves desta conta**: a principal e as limitadas com suas permissões, **Criar chave limitada** e **Revogar**.
