# Chaves restritas

Dê a cada integração uma chave com apenas as permissões de que precisa, e saiba porque o pedido de criação é recusado quando uma permissão não serve.


## Chave secreta ou restrita

Há dois tipos de chave. A chave **Secreta** (`sk_live_` ou `sk_test_`) recebe, no momento da criação, todas as permissões que quem a cria pode conceder. A chave **Restrita** (`sk_rlive_` ou `sk_rtest_`) leva só as permissões escolhidas, por isso uma fuga expõe apenas essas operações. O prefixo diz logo o tipo e o modo: `r` para restrita, `test` ou `live` para o modo.

Se o pedido trouxer `scopes` e não indicar `kind`, a chave fica restrita; sem `scopes`, fica secreta.

## Regras ao criar

- Uma chave restrita precisa de pelo menos uma permissão; sem nenhuma, a resposta é `400` com `error_code` `validation.field_required` no campo `scopes`.
- Cada permissão tem de existir no catálogo; uma desconhecida devolve `400` com `validation.invalid_choice`.
- Quem cria a chave tem de ter cada permissão que lhe dá; caso contrário, a resposta é `403`.
- As permissões de escrita que movem dinheiro (`invoices:write`, `payments:write`, `billing_runs:write`, `collections:write`, `tariffs:write`, `business:subscription:change`, `business:subscription:cancel`) só entram numa chave de teste quando o operador da instalação activou os pagamentos de teste; caso contrário, pedi-las numa chave restrita de teste devolve `400`, e uma chave secreta de teste fica sem elas.
- Só uma pessoa cria chaves: um pedido feito com uma chave de API recebe `403` com `code` `api_key_not_allowed`.
- `allowed_ips` aceita até 50 endereços IP ou intervalos CIDR; `expires_at`, se vier, tem de estar no futuro.

A chave continua a funcionar só enquanto quem a criou mantiver acesso activo e todas as permissões que ela leva. Se alguma for retirada a essa pessoa, os pedidos com a chave passam a receber `401`.

## Criar uma chave restrita

No painel, abra **Programadores** > **Chaves de API**, carregue em **Nova chave** e escolha **Restrita: à sua escolha** em **Tipo**. Use **Filtrar permissões** para encontrar cada uma, marque-as e carregue em **Criar chave**. Pela CLI, repita `--scope` por cada permissão:

```bash
gotactl api-keys create --name importacao-leituras --mode test \
  --scope business:readings:create --scope business:readings:import --out key.txt
```

Pela API, o pedido usa o token da sua sessão, porque uma chave não pode criar chaves:

```bash
curl -sS -X POST "$BUSINESS_API/developer/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Importação de leituras","kind":"restricted","mode":"test","scopes":["business:readings:create","business:readings:import"],"allowed_ips":["203.0.113.10"]}'
```

```json
{
  "id": "key_2pQ8aNcV5tY2kM7wE3rU9gZ4bXf",
  "name": "Importação de leituras",
  "kind": "restricted",
  "mode": "test",
  "prefix": "sk_rtest_C3J2",
  "last_four": "VNPk",
  "scopes": ["business:readings:create", "business:readings:import"],
  "status": "active",
  "created_by": "usr_2pQ9fLhS3jD6qA1zC8vN5mK7eRt",
  "created_at": "2026-11-19T08:30:12Z",
  "allowed_ips": ["203.0.113.10"],
  "secret": "sk_rtest_C3J27XDCG2LmlZGEONYlgCtjfIZ4SOcMz9CPVNPk"
}
```

O campo `secret` só vem nesta resposta e na de rodar a chave. Para ver que permissões pode dar, peça `GET $BUSINESS_API/developer/scopes`: devolve `data` com a lista, já limitada às que tem.

## Permissões por tarefa

| Tarefa | Operação | Permissão |
| :--- | :--- | :--- |
| Listar clientes | `listCustomers` | `business:customers:read` |
| Criar clientes | `createCustomer` | `business:customers:create` |
| Registar uma leitura | `submitManualMeterReading` | `business:readings:create` |
| Importar leituras | `importMeterReadings` | `business:readings:import` |
| Consultar facturas | `listInvoices` | `invoices:read` |
| Emitir uma factura avulsa | `issueManualInvoice` | `invoices:write` |
| Registar um pagamento | `recordPayment` | `payments:write` |
| Consultar eventos | `listDeveloperEvents` | `developer:read` |

## Quando falta uma permissão

Uma chave que só tem `business:customers:read` e tenta criar um cliente recebe:

```json
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied",
  "instance": "$BUSINESS_API/customers",
  "code": "FORBIDDEN",
  "error_code": "auth.forbidden",
  "request_id": "req_0b8e4d62a91f4c37b5d2e8f61a3c9074"
}
```

Uma chave restrita não pode ser alargada: crie outra com o conjunto certo e revogue a antiga. Rodar uma chave mantém as mesmas permissões, e só quem tem todas elas a pode rodar.

## Próximos passos

- [Ciclo de vida das chaves: rodar e revogar](/docs/getting-started/api-keys)
- [Permissões de cada operação na referência da API](/docs/api/business)
- [Preparar a passagem para produção](/docs/go-live)

