API keys

Create VMStack API keys, choose their scopes and allowed addresses, call the REST API with curl, and read the API log and rate limits.

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:

  1. Go to System › Settings and open the API tab.
  2. Under Who may create API keys, tick the levels. Administrators and resellers are ticked by default; tick users to let customers have keys too.
  3. 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#

  1. Open the user menu (your name) and choose Settings, then API keys. The panel asks for your password again.
  2. Click Create API key.
  3. 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.5 or 2001: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).
  4. 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:create and servers:delete are offered to every user, but the account's May create and delete servers switch still decides.
  • users:login can 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/json and 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": …}}. Follow links.next until it is null.
  • Anything that goes to a node (power actions, reinstall, create) answers 202 Accepted with a task to poll at /api/v1/tasks/{id}, or with the new server in status building. Webhooks remove the need to poll.
  • Every error is an RFC 9457 problem body (application/problem+json) with a stable code and a request_id. The same ID is in the X-Request-Id header and in the API log.
  • POST requests that create something take an Idempotency-Key header. 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.