# Permissions

What each key can do, by area, and the permissions that stay separate.

Updated on 5 November 2026

## How they work

Each key has only the permissions you choose when you create it. Each area has two:

- `:read` to read, for example `dns:read`;
- `:write` to change, for example `dns:write`.

If the key lacks the permission an operation asks for, the API answers `403` with the code `insufficient_scope`.

> **Note:**
>
> Each operation says the permission it needs. `GET /v1/services` uses `hosting:read`, even for servers; server operations use `vps:read`. You can already choose the areas marked "Coming soon", but they only take effect once the operations exist.

## Areas

| Area | Permissions | State |
|---|---|---|
| Account | `account:read`, `account:write` | `:read` available; `:write` has no operations yet |
| Catalog | `catalog:read`, `catalog:write` | `:read` available; `:write` has no operations yet |
| Domains | `domains:read`, `domains:write` | Available |
| DNS | `dns:read`, `dns:write` | Available |
| Hosting | `hosting:read`, `hosting:write` | Available |
| Email | `email:read`, `email:write` | Available |
| WordPress | `wordpress:read`, `wordpress:write` | Coming soon |
| VPS servers | `vps:read`, `vps:write` | Available |
| Billing | `billing:read`, `billing:write` | Available |
| Support | `support:read`, `support:write` | Available |
| Extra products | `extras:read`, `extras:write` | Available |
| Reseller | `reseller:read`, `reseller:write` | `:read` available; `:write` has no operations yet |
| SMS | `sms:read`, `sms:write` | Available |
| Webhooks | `webhooks:read`, `webhooks:write` | Coming soon |

## Dangerous permissions

These stay separate from the others and are off by default. Only turn them on for a key that really needs them.

| Permission | What for | State |
|---|---|---|
| `domains:transfer_code` | Request a domain's transfer code | Available |
| `domains:owner_change` | Change a domain's owner | Coming soon |
| `vps:reinstall` | Reinstall a server | Available |
| `vps:restore` | Restore a server from a backup | Available |
| `billing:pay` | Pay invoices with balance | Available |
| `billing:purchase` | Buy domains and extra products with credit | Available |
| `services:cancel` | Request the cancellation of a service | Available |
| `hosting:login` | Create a cPanel login link, which gives full access to the hosting | Available |
| `hosting:code` | Create FTP accounts and cron jobs, which can run code on the account | Available |
| `vps:password` | Change a server's root password and receive it in the response | Available |

## Spending limit

Each key has a spending limit: the maximum amount over 30 days, in your account's currency (for example, AOA). With the limit at 0, the key cannot spend.

In this version the API only charges credit: domain and extra product purchases, and invoices paid with credit. The [`GET /v1/limits`](https://docs.interweb.ao/en/key-status.md) operation shows the limit and what has been spent.

## Good practices

- Give each key only the permissions it needs.
- Prefer `:read` when the program only reads.
- Use different keys for different programs: if one is exposed, the others keep working.