Appearance
Using the API
Everything the panel does in the browser goes through its REST API, so anything you can click you can also script. This section is the reference for the endpoints that are documented so far; more areas are added with each release (see What is covered).
Authentication
Create a key under Panel → API Access (a reseller: API Access in its own menu). Send it with every request:
bash
curl -s -H "X-API-Key: eak_…" https://panel.example.com:2087/api/accountsAuthorization: Bearer eak_… works too, for tools that only know that header.
- A key without a reseller has an admin's rights. A key for a reseller acts as that reseller: it sees and changes that reseller's accounts only, with that reseller's permissions. It cannot use the endpoints that work on one account's own resources (Domains and DNS, marked "not a reseller key"): for those use an admin key, or sign in as the account. If the reseller is suspended or removed, its keys answer
403. - A reseller can make its own keys under API Access in its panel, when its host has given it the "Create own API keys" permission (on by default). Such a key always acts as that reseller. A reseller makes keys only while signed in to the panel (a key cannot make keys), and can hold up to 20.
- A key can expire (1 to 3650 days); after that it is refused.
- The key is shown once, when it is made. The panel keeps only a hash of it.
- Every change made with a key is in the audit log, like one made in the browser.
Limiting a key
A key can be limited, so a script gets only what it needs. Choose this when making the key, or later with Edit access in the key list (the key itself does not change).
- Read only. The key may read (
GETandHEAD) but never change anything. It can still read and download data, backups included. - Areas. The key may use only the areas you choose:
| Area | Id | Covers |
|---|---|---|
| Provisioning | provisioning | /api/v1, for billing systems such as WHMCS: create, suspend, terminate, usage |
| Accounts | accounts | Accounts, packages, resellers, resource limits, quota and disk usage |
| Domains & DNS | domains | Domains, DNS, nameservers, redirects, Cloudflare, SSL |
email | Mailboxes, forwarders, the mail queue, MailChannels, webmail | |
| Databases | databases | Databases, database users, phpMyAdmin, MariaDB tuning |
| Files & apps | files | Files, FTP, Git, WordPress, cron, PHP, staging, installers |
| Backups | backups | Backups, schedules, destinations, snapshots |
| Migrations | migrations | Importing accounts from other servers |
| Security | security | Firewall, CrowdSec, Imunify360, malware scans, WAF, SSH settings |
| Server | server | Services, software, updates, web server, network, storage, settings, fleet |
| Monitoring | monitoring | Stats, logs, the audit log, connections |
Each endpoint in this reference shows its key area, and /api/openapi.json has it as x-key-area.
- A limited key can never manage API keys, saved credentials, sign-in or two-factor, whatever its areas, so a limited key cannot make itself a bigger one.
GET /api/auth/me(who is this key?) works for every key, and never answers with a session token for a key. - A limited key signs in to nothing ("log in as" an account, phpMyAdmin, webmail and other single sign-on links), because the session it would open is not limited by the key. The exception is Provisioning: a billing system's log-in button (
/api/v1/accounts/…/sso) works for a Provisioning key that is not read only. - A limited key is refused any part of the API with no area, including parts added in later versions until they are given one.
- A reseller's limited key is limited twice: by the reseller's permissions and by its own scope.
- Keys made before 2.80.0 have full access until you limit them.
- Outside its scope a key gets
403with the reason, for exampleThis API key is read-onlyorThis API key may not use the Email area. The refusal is written to the audit log under the key's name (once per 10 minutes for the same refusal, so a script retrying in a loop cannot flood it).
For WHMCS with a reseller's key, Provisioning is the only area needed.
Instead of a key, a script can sign in with a user name and password (POST /api/auth/login) and send the token it gets as Authorization: Bearer …. A key is simpler and does not expire with a session.
Answers and errors
Requests and answers are JSON. A failed request answers with an HTTP status code and { "error": "…" } in words you can show to a person. Two exceptions: a request whose fields fail validation may answer { "errors": [ { "msg": "…", "path": "…" } ] } instead, and saving a package answers { "error": "Validation failed", "fields": { … } }. Every error also carries ref, a reference to quote when asking for support.
| Code | Meaning |
|---|---|
401 | No key or session, or the key is unknown or expired |
403 | Signed in, but not allowed this (wrong role, a reseller permission missing, the key's scope, or the panel's licence does not cover it) |
404 | No such thing, or not yours |
409 | It cannot be done in the current state (each endpoint says when) |
422 | A field is missing or invalid |
429 | Too many requests (see below) |
503 | Not available right now: the panel is in maintenance, or a service it needs (such as the nameserver) is not running |
Limits. Requests with an API key are limited to 300 per 15 minutes from one address. Signing in is limited separately, to 10, 20 or 50 attempts per 15 minutes from one address (Security settings); addresses on the panel's whitelist are not limited.
Examples
Create an account:
bash
curl -s -X POST https://panel.example.com:2087/api/accounts \
-H "X-API-Key: eak_…" -H "Content-Type: application/json" \
-d '{"username":"shop","domain":"shop.example.com","password":"a-long-password","package":"Default"}'Add a DNS record:
bash
curl -s -X PUT https://panel.example.com:2087/api/dns/shop.example.com/records \
-H "X-API-Key: eak_…" -H "Content-Type: application/json" \
-d '{"name":"www","type":"CNAME","ttl":3600,"values":["shop.example.com."]}'Suspend it, with a reason:
bash
curl -s -X POST https://panel.example.com:2087/api/accounts/shop/suspend \
-H "X-API-Key: eak_…" -H "Content-Type: application/json" \
-d '{"reason":"Unpaid invoice"}'The reference on your server
Each panel serves this reference for its own version:
https://<your panel>/api/openapi.json: OpenAPI 3.1, for code generators and tools such as Postmanhttps://<your panel>/api/docs: the same, readable in a browser
What is covered
| Area | Page |
|---|---|
| Status, signing in, API keys | Basics |
| Hosting accounts | Accounts |
| Hosting packages | Packages |
| Domains | Domains |
| DNS zones and records | DNS |
| Disks, RAID, LVM and filesystems; disk setup, fast cache and EFI copies | Storage |
The panel has other endpoints (email, databases, backups, SSL and more) that are used by its own pages and are not yet documented here. They work, but until an area is on this list its requests and answers may change between releases without notice. Documented endpoints change only with a note in the changelog, and an endpoint is never removed without notice in an earlier release.