# Permissões

O que cada chave pode fazer, por área, e as permissões que ficam separadas.

Actualizado em 05/11/2026

## Como funcionam

Cada chave tem só as permissões que escolher ao criá-la. Cada área tem duas:

- `:read` para ler, por exemplo `dns:read`;
- `:write` para alterar, por exemplo `dns:write`.

Se a chave não tiver a permissão que a operação pede, a API responde `403` com o código `insufficient_scope`.

> **Nota:**
>
> Cada operação indica a permissão de que precisa. `GET /v1/services` usa `hosting:read`, mesmo para servidores; as operações de servidores usam `vps:read`. Pode escolher já as áreas marcadas «Em breve», mas elas só terão efeito quando as operações existirem.

## Áreas

| Área | Permissões | Estado |
|---|---|---|
| Conta | `account:read`, `account:write` | `:read` disponível; `:write` ainda sem operações |
| Catálogo | `catalog:read`, `catalog:write` | `:read` disponível; `:write` ainda sem operações |
| Domínios | `domains:read`, `domains:write` | Disponível |
| DNS | `dns:read`, `dns:write` | Disponível |
| Hospedagem | `hosting:read`, `hosting:write` | Disponível |
| E-mail | `email:read`, `email:write` | Disponível |
| WordPress | `wordpress:read`, `wordpress:write` | Em breve |
| Servidores VPS | `vps:read`, `vps:write` | Disponível |
| Facturação | `billing:read`, `billing:write` | Disponível |
| Suporte | `support:read`, `support:write` | Disponível |
| Produtos extra | `extras:read`, `extras:write` | Disponível |
| Revenda | `reseller:read`, `reseller:write` | `:read` disponível; `:write` ainda sem operações |
| SMS | `sms:read`, `sms:write` | Disponível |
| Avisos automáticos | `webhooks:read`, `webhooks:write` | Em breve |

## Permissões perigosas

Estas ficam separadas das outras e vêm desligadas. Só as ligue na chave que precisar mesmo delas.

| Permissão | Para quê | Estado |
|---|---|---|
| `domains:transfer_code` | Pedir o código de transferência de um domínio | Disponível |
| `domains:owner_change` | Mudar o titular de um domínio | Em breve |
| `vps:reinstall` | Reinstalar um servidor | Disponível |
| `vps:restore` | Restaurar um servidor a partir de uma cópia | Disponível |
| `billing:pay` | Pagar facturas com saldo | Disponível |
| `billing:purchase` | Comprar domínios e produtos extra com saldo | Disponível |
| `services:cancel` | Pedir o cancelamento de um serviço | Disponível |
| `hosting:login` | Criar uma ligação de entrada no cPanel, que dá acesso total à hospedagem | Disponível |
| `hosting:code` | Criar FTP e tarefas cron, que podem correr código na conta | Disponível |
| `vps:password` | Mudar a senha de root de um servidor e recebê-la na resposta | Disponível |

## Limite de gastos

Cada chave tem um limite de gastos: o valor máximo por 30 dias, na moeda da sua conta (por exemplo, AOA). Com o limite a 0, a chave não pode gastar.

Nesta versão a API só cobra do saldo: compras de domínios e de produtos extra, e facturas pagas com saldo. A operação [`GET /v1/limits`](https://docs.interweb.ao/pt/key-status.md) mostra o limite e o que já foi gasto.

## Boas práticas

- Dê a cada chave só as permissões de que ela precisa.
- Prefira `:read` quando o programa só lê.
- Use chaves diferentes para programas diferentes: se uma ficar exposta, as outras continuam a funcionar.