# Scopes and permissions

A scope is a right you give to a token. The names are in the form `area:action`.

## The four checks

Every request must pass all four, at the moment it is made:

1. **Token.** The token has the scope. It has not expired, the caller's address is allowed, and the site or server is inside the token's limits.
2. **Plan and platform.** The team's plan includes the scope. A platform administrator can switch the whole API or single scopes off for a team.
3. **Team owner's rules.** The owner sets, under **API**, then **Rules**: which scopes tokens may have, who may make tokens (owners, admins, or any member), the longest token life, and whether allowed addresses are required.
4. **The maker's permissions.** The person who made the token must still be in the team, must have two-factor sign-in if the team needs it, and must hold the team permissions listed below. Per-server and per-site access rules of that person apply too.

If any check fails, you get `403` (or `404` for something outside your reach). `GET /token` shows `blocked_scopes` with the reason.

## Risk levels

- **low**: reads without secrets.
- **medium**: changes you can undo, or text that may contain private data (logs).
- **high**: secrets, running code, restores and server changes.
- **critical**: people and deleting.

## All scopes

| Scope | Risk | What it allows | Team permissions needed |
| --- | --- | --- | --- |
| `servers:read` | low | Servers, health, security report, databases, firewall, PHP settings, recipes, server backups list. | View servers |
| `servers:write` | high | Add and connect servers, reboot, firewall, databases, PHP, services, security checks and fixes, recipes, SSH keys. | View servers, Manage servers |
| `sites:read` | low | Sites, settings, services, scheduled jobs, redirects, environments, move and standby status, certificates. | View sites |
| `sites:write` | medium | Create and import sites, change settings, services, jobs, redirects, HTTPS, environments, standbys, moves, GitHub connection. | View sites, Manage sites |
| `deployments:read` | low | Deployment history, status and log. | View sites |
| `deployments:write` | medium | Deploy, roll back, promote an environment. | View sites, Deploy sites |
| `env:read` | high | Read a site's `.env`, with its secrets. | View sites, View site secrets |
| `env:write` | high | Replace or change `.env` keys. | View sites, View site secrets |
| `backups:read` | low | List site and server backups. | View sites |
| `backups:write` | high | Back up now and restore a database. | View sites, Manage sites |
| `logs:read` | medium | Read Laravel, Nginx and app logs. | View sites, View site secrets |
| `commands:run` | high | Run a command in a site's folder as the site's user. | View sites, Manage sites, View site secrets |
| `dns:read` | low | Which DNS records a site needs, which domains pfcloud can manage. | View sites |
| `dns:write` | medium | Create missing A records. Never changes existing records. | View sites, Manage sites |
| `team:read` | low | Members, invitations, alert settings, activity log. | View audit log |
| `team:write` | critical | Invite people and cancel invitations. | Create invitation, Cancel invitation |
| `certificates:renew` | medium | Renew a Let's Encrypt certificate now. | View sites |
| `deletions:request` | critical | Ask to delete a server, site or database. Nothing is deleted until a human approves. | Delete resources |

Some endpoints need two scopes, for example `GET /servers/{server}/certificates` needs `servers:read` and `sites:read`. Every endpoint's scope is shown in the API reference pages, for example [Sites](/developers/api-sites).

## Examples of scope sets

| Job | Scopes |
| --- | --- |
| Status dashboard | `servers:read`, `sites:read`, `deployments:read` |
| CI deploy step | `sites:read`, `deployments:read`, `deployments:write` |
| Certificate watcher | `servers:read`, `sites:read`, `certificates:renew` |
| Infrastructure script | `servers:read`, `servers:write`, `sites:read`, `sites:write` |

For AI tokens see [AI token recipes](/developers/ai-token-recipes).

## Why scopes alone are not enough

A scope is permission to call a group of endpoints, not a promise that every call is harmless. `sites:write` can change Nginx settings and services. `servers:write` can open firewall ports. Limit the token to the servers and sites it needs, set a short expiry, and review the activity. See [AI security](/developers/ai-security).