Skip to content

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/accounts

Authorization: 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 (GET and HEAD) but never change anything. It can still read and download data, backups included.
  • Areas. The key may use only the areas you choose:
AreaIdCovers
Provisioningprovisioning/api/v1, for billing systems such as WHMCS: create, suspend, terminate, usage
AccountsaccountsAccounts, packages, resellers, resource limits, quota and disk usage
Domains & DNSdomainsDomains, DNS, nameservers, redirects, Cloudflare, SSL
EmailemailMailboxes, forwarders, the mail queue, MailChannels, webmail
DatabasesdatabasesDatabases, database users, phpMyAdmin, MariaDB tuning
Files & appsfilesFiles, FTP, Git, WordPress, cron, PHP, staging, installers
BackupsbackupsBackups, schedules, destinations, snapshots
MigrationsmigrationsImporting accounts from other servers
SecuritysecurityFirewall, CrowdSec, Imunify360, malware scans, WAF, SSH settings
ServerserverServices, software, updates, web server, network, storage, settings, fleet
MonitoringmonitoringStats, 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 403 with the reason, for example This API key is read-only or This 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.

CodeMeaning
401No key or session, or the key is unknown or expired
403Signed in, but not allowed this (wrong role, a reseller permission missing, the key's scope, or the panel's licence does not cover it)
404No such thing, or not yours
409It cannot be done in the current state (each endpoint says when)
422A field is missing or invalid
429Too many requests (see below)
503Not 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 Postman
  • https://<your panel>/api/docs: the same, readable in a browser

What is covered ​

AreaPage
Status, signing in, API keysBasics
Hosting accountsAccounts
Hosting packagesPackages
DomainsDomains
DNS zones and recordsDNS
Disks, RAID, LVM and filesystems; disk setup, fast cache and EFI copiesStorage

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.

EasyCP — the hosting control panel for AlmaLinux.