Scopes
Scopes limit what an access token can do in Server Chief. Choose them when you create an access token. Start with the narrowest scope that covers your integration. The shared scopes guide explains how parent scopes and write access work.
Each endpoint in the REST API reference lists its required scope under security.
Available scopes
Broad scopes
| Scope | Access |
|---|---|
serverchief | Every user-facing Server Chief API operation |
serverchief:read | Every resource read operation |
serverchief:write | Every resource write and read operation |
Servers
| Scope | Access |
|---|---|
serverchief:servers:read | List and retrieve servers and their inventory: packages, software, sites, certificates, package sources, vulnerabilities, metrics, install commands, and agent releases |
serverchief:servers:write | Create, update, and delete servers, refresh their inventory, update their agent, set their tags, and create or revoke install commands; also grants server reads |
Tags
| Scope | Access |
|---|---|
serverchief:tags:read | List tags and see which teams they are shared with |
serverchief:tags:write | Create, update, delete, and share tags; also grants tag reads |
Setting the tags of a server needs serverchief:servers:write. The tags scopes cover the tags themselves and their sharing.
Alerts
| Scope | Access |
|---|---|
serverchief:alerts:read | List metric alert rules and the alerts they raised |
serverchief:alerts:write | Create, update, and delete metric alert rules; also grants alert reads |
Webhooks
| Scope | Access |
|---|---|
serverchief:webhooks:read | List webhook endpoints, event types, events, and deliveries with their requests and responses |
serverchief:webhooks:write | Create, update, enable, disable, and delete webhook endpoints, rotate their signing secrets, send test events, and resend events and deliveries; also grants webhook reads |
Signing secrets are only returned when an endpoint is created or its secret is rotated, so a read token cannot sign requests.
Scopes are hierarchical. A resource write scope includes the matching read scope. serverchief:read grants every resource read scope, serverchief:write grants every resource write and read scope, and serverchief grants everything. A resource scope does not grant access to unrelated resources.
Example token configurations
Report on your fleet
Code
The token can search servers and read their inventory, vulnerabilities, and metrics. It cannot change anything.
Add servers from provisioning
Code
The token can create and revoke install commands for new servers. An install command takes the names or IDs of the tags every server it adds gets, so the integration does not need a tags scope.
Manage alert rules
Code
The token can manage metric alert rules and read the tags that rules can watch. Add serverchief:servers:read to scope rules to individual servers by their ID.