> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vmarea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Escopos e permissões

> Lista completa de escopos disponíveis para tokens de API da VMArea e o que cada um permite.

Os tokens de API carregam um subconjunto de permissões escolhidas no momento da criação. Cada escopo concede acesso a um grupo de recursos específico. Sessões do painel (login pelo navegador) têm todos os escopos implicitamente; tokens de API têm apenas os selecionados explicitamente.

## Escopos disponíveis

### Máquinas virtuais

| Escopo      | Descrição                                                                                                                                                         |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vms:read`  | Listar e recuperar máquinas virtuais, status, ações e acesso ao console.                                                                                          |
| `vms:write` | Criar, modificar, excluir e executar ações de ciclo de vida em máquinas virtuais (iniciar, parar, reiniciar, reconstruir, redimensionar, snapshot, backup, etc.). |

### Redes privadas

| Escopo           | Descrição                                                              |
| ---------------- | ---------------------------------------------------------------------- |
| `networks:read`  | Listar e recuperar redes privadas e suas VMs conectadas.               |
| `networks:write` | Criar, atualizar e excluir redes privadas; conectar e desconectar VMs. |

### Firewalls

| Escopo            | Descrição                                                                  |
| ----------------- | -------------------------------------------------------------------------- |
| `firewalls:read`  | Listar e recuperar regras e vínculos de firewall.                          |
| `firewalls:write` | Criar, atualizar e excluir firewalls; gerenciar regras e vínculos com VMs. |

### Chaves SSH

| Escopo           | Descrição                                           |
| ---------------- | --------------------------------------------------- |
| `ssh-keys:read`  | Listar e recuperar chaves públicas SSH armazenadas. |
| `ssh-keys:write` | Adicionar, atualizar e excluir chaves públicas SSH. |

### Backups e snapshots

| Escopo          | Descrição                                                     |
| --------------- | ------------------------------------------------------------- |
| `backups:read`  | Listar backups e snapshots e ver o histórico de restaurações. |
| `backups:write` | Criar, excluir e restaurar backups e snapshots.               |

### Webhooks

| Escopo           | Descrição                                                                   |
| ---------------- | --------------------------------------------------------------------------- |
| `webhooks:read`  | Listar assinaturas de webhook e ver o histórico de entregas.                |
| `webhooks:write` | Criar, atualizar e excluir assinaturas de webhook; enviar eventos de teste. |

### Faturamento

| Escopo         | Descrição                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `billing:read` | Ler saldo da carteira, visualizar faturas e verificar o uso de bandwidth. O faturamento é somente leitura; recargas são feitas pelo painel. |

## Leituras do catálogo

Buscar planos, regiões e templates de SO não exige nenhum escopo específico. Qualquer token válido pode ler os dados do catálogo.

## Escopo ausente — resposta 403

Quando uma requisição usa um token que não possui o escopo necessário, a API retorna:

```json theme={null}
{
  "success": false,
  "error": "Forbidden"
}
```

com o status HTTP `403`.