Scopes and permissions
Every scope with its risk, the team permission it needs, and the four checks every request passes.
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:
- 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.
- 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.
- 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.
- 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.
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.
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.