API tokens
Create scoped tokens to manage a workspace from scripts and tools.
An API token lets a script or tool, such as Terraform or a CI job, act in one workspace. Each token has scopes that limit what it can do, so give it only what it needs.
Create a token#
Owners and admins create tokens from API tokens in the workspace. Choose:
- A name, so you can tell tokens apart later.
- Scopes: see below.
- Expiry: 30 days, 90 days, 1 year or never.
The token is shown once, when you create it. It starts with vm_. Store it somewhere safe, like a secrets manager. Later, only its first few characters are shown, so you can recognise it.
Use a token#
Send it in the Authorization header:
# The API's address, shown at the top of the API reference
export API=https://api.example.com
export TOKEN=vm_...
curl "$API/servers" \
-H "Authorization: Bearer $TOKEN"A token belongs to one workspace, so you don’t name the workspace: /servers, /backups, /ssh-keys, /billing, /activity and /tickets act on the token’s own. Requests and responses are JSON. Errors come back as {"error": "…"} with a 4xx status, and the message says what was wrong.
Scopes#
| Scope | Lets the token |
|---|---|
servers:read |
See servers, their network and activity |
servers:write |
Power, rename, rebuild, set reverse DNS, and take snapshots |
servers:destroy |
Destroy servers |
backups:read |
See backups |
backups:write |
Take, restore and delete backups, and turn them on or off |
ssh_keys:read |
See SSH keys |
ssh_keys:write |
Add and remove SSH keys |
billing:read |
See invoices, subscriptions and billing details |
billing:write |
Pay invoices and change billing details |
members:read |
See members and invites |
audit:read |
See the activity log |
support:read |
See the workspace’s support tickets |
support:write |
Open, reply to and close support tickets |
Some actions can’t be done with a token at all and need someone signed in to the dashboard: managing members and invites, creating tokens, and renaming or deleting the workspace.
Tokens and roles#
A token can never do more than the person who created it. You can only give it scopes your role has. If your role later changes, your tokens are limited to what your new role allows. If you leave the workspace, they stop working.
Revoke a token#
Revoke a token from API tokens as soon as you don’t need it, or if it may have leaked. It stops working straight away.