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.