API scopes

Every Servor API scope and what it grants — servers:read, monitors:read, status-pages:read, incidents:read, incidents:write, commands:read and audit:read.

Scopes decide exactly what an API token can do. You pick them when you create a token, and a request that needs a scope the token doesn't carry returns 403. This page lists every scope Servor offers and what each one grants, so you can keep each token least-privilege.

Read-first by design

The public API is a read-and-automate-incidents surface. There are no write scopes for infrastructure (servers, monitors, status pages) and no command execution over the API — those actions stay in the dashboard. See the API overview for why.

The complete list

These are the only scopes that exist. Anything not listed here isn't available.

Scope	Grants
`servers:read`	Read your servers — list them and fetch a single server's details.
`commands:read`	Read a server's command history (the recorded log of what ran).
`monitors:read`	Read your monitors and their recent checks.
`status-pages:read`	Read your status pages, their components and their incidents.
`incidents:read`	List incidents, fetch one and read its update timeline.
`incidents:write`	Create incidents, post updates and resolve them.
`audit:read`	Read your team's audit log of recorded activity.

What each scope unlocks

`servers:read`

Grants read access to the Servers API: list every server in your team and fetch a single server by id. Responses never include SSH credentials or any encrypted data. To add or edit a server, use the dashboard — see add a server.

`commands:read`

Grants read access to a server's command history — the searchable record of commands that ran on it. This scope is read-only: the API never runs commands. To execute something, use the web terminal or run commands in the dashboard.

`monitors:read`

Grants read access to the Monitors API: list your monitors and pull the recent checks for one. Handy for exporting uptime or building your own dashboards. Create monitors in the dashboard — see create a monitor.

`status-pages:read`

Grants read access to the Status pages API: list your status pages, read a single page with its components, and read the incidents attached to it. Build or edit pages in the dashboard — see create a status page.

`incidents:read`

Grants read access to the Incidents API: list incidents, fetch a single one and read its full update timeline. Pair it with status-pages:read when you want the incidents shown on a specific page.

`incidents:write`

The one write scope. It lets a token create incidents, post updates and resolve them (post an update with status=resolved). This is what makes the API ideal for wiring your own alerting into Servor. Grant it only to a service that genuinely opens or updates incidents — see report an incident and update and resolve. Reading incidents still requires incidents:read.

`audit:read`

Grants read access to the Audit API — your team's log of recorded activity, including token usage. Useful for compliance exports and for watching how your own tokens are being used.

Choosing scopes

Start read-only

Give a new token only the read scopes it needs, then add incidents:write if — and only if — the integration has to change incidents. One token per integration makes it safe to revoke a single one without breaking everything else. Create a token in Servor.

A few common combinations:

Status mirror / uptime export — monitors:read, status-pages:read.
Incident automation (open on alert, resolve on recovery) — incidents:write plus incidents:read to reconcile state.
Inventory / reporting script — servers:read, commands:read, audit:read.

Scopes vs. team roles

Scopes limit a token; roles limit a person. A token can never exceed what the API exposes — even incidents:write can't create servers, because no such API scope exists. Managing tokens is itself an admin capability, and the public API requires the AI plan; see plans and limits.