Access tokens

Creating a token

Create tokens under Settings → Connections → API tokens. Give the token a name, choose its scopes, and set an expiry of 30 days, 90 days, a year, or never. You must be signed in and enter your password again. Another token cannot create one.

The token is shown once. Provisore stores only a hash, so it cannot show it again. If you lose it, create a new one. The list shows a masked identifier for each token, the same one the audit log records.

Scopes

servers:read · servers:write
  registration, provisioning, reboot, tags, config files

sites:read · sites:write
  sites, aliases, forced HTTPS, maintenance, redirects, certificates

deployments:read · deployments:write
  deploy, roll back, and the site's deploy script

operations:read · operations:write
  databases, daemons, cron, firewall, commands, recipes, backups

observability:read · observability:write
  metrics, logs, jobs, alerts, monitors, channels, audit entries

secrets:read · secrets:write
  environment files, database passwords, deploy-hook tokens, SSH keys;
  write also runs anything as the provisore account

account:read
  the team record and integration status

• Write includes read in the same area. A token that can create a deployment can also list deployments.
• Secrets stand apart. No other scope grants secrets:read, including secrets:write. A token can ship a new environment file without reading the current one, and a CI token can deploy without reading the environment at all.

What a token cannot do

• Manage tokens, change a password, enrol or disable two-factor authentication, or access billing. These need a signed-in session.
• Change team membership or roles.
• Run a command or recipe as root.
• Run anything as the provisore account without secrets:write. That account can use sudo, so commands and recipes run as it, and daemons and cron entries that run as it, need the scope.
• Act on another team. A token belongs to the team it was created in.
• Exceed its owner's role. If the owner is demoted, their tokens drop to the new role on the next request. If the owner leaves the team, the tokens stop working.

Using and revoking a token

curl https://provisore.com/v1/servers -H "Authorization: Bearer pvs_…"

Revoking takes effect on the token's next request. Revoked tokens stay in the list, marked revoked. The audit log records requests made with a token, including denied ones. Signing out, changing your password and resetting it leave tokens working.