> ## 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.

# Scopes & permissions

> API tokens carry a subset of permissions chosen at creation. This page lists every available scope and what it grants.

API tokens carry a subset of permissions chosen at creation time. Each scope grants access to a specific resource group. Dashboard sessions (browser login) implicitly hold all scopes; API tokens hold only those explicitly selected.

## Available scopes

### Virtual machines

| Scope       | Description                                                                                                                            |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `vms:read`  | List and retrieve virtual machines, their status, actions, and console access.                                                         |
| `vms:write` | Create, modify, delete, and run lifecycle actions on virtual machines (start, stop, restart, rebuild, resize, snapshot, backup, etc.). |

### Private networks

| Scope            | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| `networks:read`  | List and retrieve private networks and their VM attachments.        |
| `networks:write` | Create, update, and delete private networks; attach and detach VMs. |

### Firewalls

| Scope             | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `firewalls:read`  | List and retrieve firewall rules and bindings.                      |
| `firewalls:write` | Create, update, and delete firewalls; manage rules and VM bindings. |

### SSH keys

| Scope            | Description                               |
| ---------------- | ----------------------------------------- |
| `ssh-keys:read`  | List and retrieve stored SSH public keys. |
| `ssh-keys:write` | Add, update, and delete SSH public keys.  |

### Backups & snapshots

| Scope           | Description                                          |
| --------------- | ---------------------------------------------------- |
| `backups:read`  | List backups and snapshots and view restore history. |
| `backups:write` | Create, delete, and restore backups and snapshots.   |

### Webhooks

| Scope            | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| `webhooks:read`  | List webhook subscriptions and view delivery history.               |
| `webhooks:write` | Create, update, and delete webhook subscriptions; send test events. |

### Billing

| Scope          | Description                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `billing:read` | Read wallet balance, view invoices, and check bandwidth usage. Billing is read-only; top-ups are handled through the dashboard. |

## Catalog reads

Fetching plans, regions, and OS templates does not require any specific scope. Any valid API token can read catalog data.

## Missing scope — 403 response

When a request uses a token that lacks the required scope, the API returns:

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

with HTTP status `403`.