Every request is authenticated with an API token sent in the Authorization header:
Authorization: Bearer hostoff_your_tokenThere are no sessions, cookies or CSRF tokens: each request stands on its own.
Creating a token
Tokens are created on Settings → API Tokens in the panel. Creating one asks for your account password again, because a token is access that outlives your session. When you create a token you choose:
- a name, so you know later what it is used for;
- abilities: what the token may do (see below);
- expiry: 1, 7, 30, 90 or 365 days, or no expiry;
- allowed IP addresses (optional): up to 20 addresses or CIDR ranges the token can be used from.
The token is shown once, right after it is created. We store only its hash and cannot show it again: if you lose it, revoke it and create a new one. An account can have up to 10 active tokens.
Abilities
A token can do only what its abilities allow. Abilities do not include each other: a token that changes servers but cannot read them is possible, so list every ability you need. A token with all rights at once (*) is never issued.
| Ability | What it allows |
|---|---|
account:read |
account details, balance and billing limits |
vps:read |
server list and details, status, graphs, traffic, activity, rDNS, backups list, SSH keys, the order catalog |
vps:power |
start, shut down, stop, reboot, reset |
vps:manage |
name, notes, rDNS, password, SSH keys, primary IP, IPv6, console, creating and deleting backups. This is root access to the servers in practice |
vps:billing |
everything that charges the balance or changes future charges: ordering, renewal, auto-renewal, billing period, IP replacement, additional IPv4, the backup add-on |
vps:destroy |
the irreversible: reinstalling, restoring from a backup, deleting a server |
A request outside the token's abilities is 403 forbidden. Give each integration its own token with the smallest set of abilities it needs, and give vps:destroy only to the tokens that really delete or reinstall servers.
IP restrictions
- A token with its own list of allowed addresses works only from those addresses.
- A token without a list follows your account's IP whitelist, when you have one enabled in the panel.
- A request from an address that is not allowed is
403 forbidden. Such attempts are recorded in your account's activity log.
We strongly recommend restricting every production token to the addresses of the servers that call the API.
When a request is refused
| Answer | Why |
|---|---|
401 unauthenticated |
no token, an unknown or revoked token, or an expired one |
403 forbidden |
the token lacks the ability; the request comes from an address that is not allowed; API access is not enabled for the account; the account is blocked or its e-mail address is not verified |
The message of the error tells these cases apart, but your code should rely on the code and the HTTP status. See Responses and errors.
Keeping tokens safe
- Keep tokens on your servers only. Never put a token into a web page, a mobile app or a public repository.
- Use a separate token for each integration and environment, so one can be revoked without stopping the others.
- Prefer tokens that expire, and rotate long-lived ones.
- If a token may have leaked, revoke it on Settings → API Tokens at once: it stops working with the next request.