An API key lets a billing system or a script act as one account through the REST API. The key belongs to the account that created it. It sees and does what that account sees and does in the panel, and no more. On top of that, each key has scopes, an optional list of allowed addresses and an expiry. Every request it makes is written to the API log.
This page covers keys and the basics of calling the API. Every operation, its fields and its answers are in the API reference.
Who may create keys#
Each account creates its own keys and nobody else's. An administrator cannot create a key for a customer. Staff who need to act on a customer's servers use their own key. They reach the customer's servers through it, or use a one-time sign-in link (scope users:login) to send the customer's browser into the panel.
Which account levels may have keys is a panel setting:
- Go to System › Settings and open the API tab.
- Under Who may create API keys, tick the levels. Administrators and resellers are ticked by default; tick users to let customers have keys too.
- Click Save.
Note: When you untick a level, its existing keys stop working as well. They work again once the level is ticked again.
On the same tab:
| Setting | Default | What it does |
|---|---|---|
| Who may create API keys | Administrators, resellers | Levels whose accounts may create and use keys. |
| Administrator keys must have allowed addresses | On | An administrator's key with no allowed addresses is refused, at creation and at every request. |
| Requests a minute per key | 240 | The default general rate limit (10 to 6000). A single key can have its own limit under System › API keys. |
| AI agents may connect to the MCP server | On | The panel-wide switch for the MCP server. |
How long the API log is kept is set under System › Settings › Logs.
Creating a key#
- Open the user menu (your name) and choose Settings, then API keys. The panel asks for your password again.
- Click Create API key.
- Fill in the form:
- Name: your own label, such as the system that uses the key (up to 60 characters).
- Scopes: what the key may touch. Use one of the presets (Read only, Billing system, Full access) and adjust the boxes as needed. Only the scopes your account level can use are offered.
- Allowed addresses: up to 20 IPv4 or IPv6 addresses or networks, such as
203.0.113.5or2001:db8::/48. Empty means any address. This is required for administrators while the panel setting above is on. - Expires: 1 day, 7 days, 30 days, 90 days, 1 year (the default) or Never (for billing integrations).
- Click Create key. The page shows the whole key once, under Your new API key, with Copy key. Copy it now: only a hash is stored, and afterwards the panel shows only its public part,
vmk_<12 characters>….
A key looks like vmk_ followed by a 12-character public id, an underscore and 40 random characters. The fixed vmk_ prefix lets secret scanners recognise a leaked key.
What you should know about keys:
- An account can have up to 25 keys that work at the same time.
- Creating a key mails the account's owner, naming the key and the address it was created from. The owner is mailed again 7 days before a key expires (optional, under Settings › Notifications). After 10 wrong secrets for one key within a minute, the owner gets a mail too.
- You can change a key's name, scopes and allowed addresses with Edit. The secret itself can never be changed or shown again.
- Revoke stops the key at once. The row stays, so the log and the audit still name it.
- Changing the account password under Settings › Security does not revoke keys, so billing integrations keep working. Resetting the password with a Forgot password link revokes every key of the account.
- Keys of a suspended account stop working (403
account_suspended) and work again when the suspension is lifted. Deleting an account deletes its keys. - Click a key's row to see its last 100 requests.
Scopes#
A request needs the operation's scope and the account's own right to do it. A scope never adds a right that the account's level lacks. Scopes are checked against the account's level at every request, so a level that loses a right loses the matching scopes at once. There is no scope for managing keys: a leaked key cannot create its own successor.
A = administrator, R = reseller, U = user (customer).
| Scope | Covers | Offered to |
|---|---|---|
servers:read |
List and show servers, their addresses and activity | A R U |
servers:create |
Create servers | A R U |
servers:delete |
Delete servers | A R U |
servers:power |
Start, shut down, reboot and power off servers | A R U |
servers:manage |
Reinstall, rescue, reset the password, reconfigure the network | A R U |
servers:secrets |
Read root and rescue passwords | A R U |
servers:provision |
Suspend, upgrade, addresses, owner, limits | A R |
firewall:read |
Read firewalls | A R U |
firewall:write |
Change firewalls | A R U |
backups:read |
Read backups | A R U |
backups:write |
Back up, restore and delete backups | A R U |
snapshots:read |
Read snapshots and a server's snapshot policy | A R U |
snapshots:write |
Take, rename, revert to and delete snapshots | A R U |
disks:read |
Read a server's disks | A R U |
disks:write |
Add, grow, attach, detach, label and delete a server's disks | A R U |
usage:read |
Charts and traffic | A R U |
usage:write |
Set your own usage alerts | A R U |
networks:read |
Private networks and the servers on them | A R U |
networks:write |
Make, rename and delete private networks; put servers on them and take them off | A R U |
ssh-keys:read |
Read your saved SSH keys | A R U |
ssh-keys:write |
Change your saved SSH keys | A R U |
users:read |
Read the accounts you manage | A R |
users:write |
Change the accounts you manage | A R |
users:login |
One-time sign-in and console links (full sessions of the accounts you manage) | A R |
branding:read |
Read the brand: the panel's, or your own as a reseller | A R |
branding:write |
Change the brand's name, colour, sign-in message and links | A R |
catalog:read |
Plans, locations, images and ISOs | A R U |
plans:write |
Change hosting plans | A R |
infrastructure:read |
Nodes and IP pools | A |
infrastructure:write |
Change nodes, IP pools, locations, images and ISOs | A |
tasks:read |
Tasks | A R U |
audit:read |
The audit log, the sign-in log and the allowed addresses of administrators | A |
security:read |
Security advisories and findings | A |
webhooks:read |
Your webhook endpoints, their deliveries and the events | Levels allowed webhooks |
webhooks:write |
Add, change, test and delete your webhook endpoints; resend deliveries | Levels allowed webhooks |
team:read |
Your account's team members and invitations | U |
team:write |
Invite, change roles and remove team members | U |
Notes on particular scopes:
servers:createandservers:deleteare offered to every user, but the account's May create and delete servers switch still decides.users:logincan open a full panel session of any account the key's account manages. Give it only to a billing system you trust, and set allowed addresses. The key form warns you when you tick it.- An administrator with a staff role is only offered the scopes that role allows.
The presets tick these boxes:
| Preset | Ticks |
|---|---|
| Read only | Every :read scope offered to the account |
| Billing system | servers:*, users:*, backups:*, snapshots:*, disks:*, webhooks:*, usage:read, catalog:read, tasks:read, firewall:read |
| Full access | Every scope offered to the account |
Making a request#
- Base URL:
https://panel.example.com/api/v1/. The version is in the path. Within v1, changes are additive only, so ignore response fields you do not know. - Authentication: the header
Authorization: Bearer vmk_…. There is no other way: no query parameter, no cookie, no session. A browser signed in to the panel gets 401 without a key. - HTTPS only. A request over plain HTTP is refused with 403
https_required. Revoke a key that was sent in clear. - JSON only. Bodies are
Content-Type: application/jsonand at most 64 KB. A field that the operation does not take is refused with 422, so a typo never silently does nothing.
To test a key, call GET /me. It returns the key's account, the key's effective scopes, its expiry and its rate limit:
curl -s https://panel.example.com/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
To list the running servers the key can see:
curl -s "https://panel.example.com/api/v1/servers?filter[status]=running&limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"
YOUR_API_KEY is the whole key as shown once at creation (vmk_…).
Answers and errors follow a few rules:
- One resource is
{"data": {…}}. A list is{"data": […], "meta": {"next_cursor": …}, "links": {"next": …}}. Followlinks.nextuntil it is null. - Anything that goes to a node (power actions, reinstall, create) answers
202 Acceptedwith a task to poll at/api/v1/tasks/{id}, or with the new server in statusbuilding. Webhooks remove the need to poll. - Every error is an RFC 9457 problem body (
application/problem+json) with a stablecodeand arequest_id. The same ID is in theX-Request-Idheader and in the API log. POSTrequests that create something take anIdempotency-Keyheader. A repeat with the same key and body within 24 hours gets the first answer back instead of creating a second server.
Rate limits#
| Bucket | Limit |
|---|---|
| General, per key | 240 requests a minute (or the panel's default, or the key's own limit) |
| Expensive writes, per key | 30 a minute: server create, reinstall, delete and upgrade, back up now, webhook tests and resends |
| Passwords, per key | 30 a minute: root-password reads, an account's new password, a reset with a typed password |
| Failed authentication, per client address | 20 failures a minute for one key's public id, 50 over all keys |
| Requests without a valid key, per client address | 60 a minute |
Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds) for the general bucket. A 429 carries Retry-After. A key with the right secret is never held back by the failed-authentication limits.
To give one key a different general limit, go to System › API keys, find the key and set its rate limit.
Managing keys as an administrator#
- System › API keys lists every key of the panel with its owner, level, scopes, allowed addresses, expiry and last use. Filter by owner, level, status, keys unused for 90 days or keys with no allowed addresses. You can revoke any key (with a reason) and set a key's own rate limit. The dashboard counts keys unused for 90 days.
- A user's page has an API keys card listing that account's keys, with Revoke. Administrators and the account's reseller see it. There is no create button there, by design.
The API log#
Every API request is logged after its answer is sent: the key (public id only), the account, the method, the route template, the path, the names of the query parameters (not their values), the status, the problem code, the duration, the client address, the user agent and the request ID. Request and response bodies are never logged. The audit log records what each write changed, and its entries carry via: "api" and the key's public id.
To read it:
- Administrators: System › API log. Filter by key, account, route (such as
servers/{server}), answer status class, problem code, client address, dates or request ID. - Every account: Settings › API keys, then click a key to see its last 100 requests.
The log is kept 30 days by default (7 to 365), set under System › Settings › Logs. When a customer reports a failed call, ask for the request_id from the error body and search for it in the API log.