Skip to content

API Keys ​

An API key lets an external application authenticate against the panel's REST API. Each key can be turned off, limited to a set of endpoints, and limited to a set of source addresses.

API Keys

Overview ​

URL: /admin/settings/api-keys

Open it from Settings > Security > API Keys in the sidebar. The entry carries a counter showing how many keys exist, and a fresh server has none, so the list opens on No API Keys.

An Integration Overview box at the top of the page links to the API documentation served by this server.

The key list ​

ColumnMeaning
NameThe label you gave the key.
API KeyThe public token sent with each request.
API SecretThe private counterpart. Hidden by default.

The search box covers all three columns, and the page size can be set to 5, 10, 25, 50, or All. Each row offers Edit and Delete; deleting a key stops every integration using it, immediately.

Creating a key ​

Create API Key opens Create API Key at /admin/settings/api-keys/create.

The Security Settings and Endpoint Access sections of Create API Key, with Allow writes that run commands as root off

The form is grouped into three sections:

API Key Details ​

  • Name (required) - a descriptive name that identifies the integration.
  • API Key and API Secret - both read Generated automatically. You do not choose them, and the secret is shown to you only once the key is created, so store it before you leave the page.

Security Settings ​

  • Enable API Key - whether the key can be used at all. Turning it off is the quickest way to suspend an integration without deleting its key.
  • IP Restriction - limits the key to the source addresses you list.

Endpoint Access ​

  • Allow all endpoints - when on, the key reaches every API route except those that need an explicit grant. When off, only the endpoints and methods you select are allowed.
  • Endpoints that need an explicit grant - shown while Allow all endpoints is on, since panel 1.9.4. Some endpoints run commands on the server as any user, root included, or sign in to the admin panel, so Allow all endpoints does not include them. Select each one this key may use. With Allow all endpoints off, they are in the endpoint picker like any other endpoint. The list holds:
    • the server's cron jobs under /api/admin/cron-jobs, which run any command as any user, root included;
    • since panel 1.9.5, the admin panel sign-in link, POST /api/admin/generate-sso-token. The link opens a full admin panel session, which the key's endpoint list does not limit. See Admin panel sign-in links;
    • since panel 1.9.5, the LVE Manager sign-in token, POST /api/admin/cloudlinux/lvemanager/sso-token. The token opens the LVE Manager interface, where the CloudLinux limits and options of every account are set.
  • Allow writes that run commands as root - since panel 1.9.5, on administrator keys only, and off by default. It lets the key make the administrator API writes that amount to running commands as root on the server, such as the content of a Fail2Ban action. Anyone holding a key with this permission holds root access to the server, so turn it on only for automation you trust as much as root, and combine it with IP Restriction. See Writes that run commands as root.

A key that calls an endpoint it has no explicit grant for is refused with HTTP 403 and "reason": "explicit_grant_required", and the answer names the endpoint.

Create saves the key, Create & create another reopens an empty form, and Cancel returns to the list.

Editing a key ​

Edit on a row reopens the same three sections with the current values, so you can rename a key, disable it, tighten its endpoint list, or change its address restriction. Save Changes applies the change. The secret is not shown again; issue a new key if it has been lost.

Acting on behalf of a hosting account ​

An admin API key can call any /api/client/* endpoint on behalf of a hosting account, so an automation does not need a separate key per account. Name the account in the X-Hosting-Account header, using either its numeric id or its username:

bash
curl https://server.example:8443/api/client/domains \
  -H "X-API-Key: <your-key>" \
  -H "X-API-Secret: <your-secret>" \
  -H "X-Hosting-Account: alice"

Rules that apply:

  • The header is required. An admin key never acts on a client endpoint implicitly; without the header the request is refused, so a missing header can never be interpreted as "any account".
  • Endpoint ACLs apply as usual. A key with Allow all endpoints turned off reaches only the client endpoints you selected.
  • A reseller key can only name accounts it owns. An account outside the reseller's own set is reported as not found, so a reseller cannot learn whether an account exists elsewhere on the server.

Every query the endpoint runs is scoped to the named account, exactly as it would be for that account's own key.

The account's plan and suspension ​

Since panel 1.9.4, every client API endpoint belongs to a feature of the account's hosting plan, as the matching client panel page does. When the plan's Feature List leaves that feature out, the endpoint is refused with HTTP 403 for your key too, and the answer names the feature ("feature": "databases", for example). Account details, server services, and the file manager belong to no plan feature.

A suspended account's own API keys are refused on every call. Your key keeps working on a suspended account, so it can still be managed. The client side of these rules is described in Client API Keys.

Writes that run commands as root ​

Since panel 1.9.5, some writes of the administrator API need the key's Allow writes that run commands as root permission, because what they save runs as root on the server. A key without it is refused with HTTP 403; with it, the write works as before. Reads stay allowed, except a download of the server's own files from Acronis. The panel's own pages are not affected: the permission belongs to API keys.

Method and pathWhat needs the permission
POST /api/admin/fail2ban/actions, PATCH /api/admin/fail2ban/actions/{id}Creating a Fail2Ban action, or changing its content.
POST /api/admin/fail2ban/jails, PATCH /api/admin/fail2ban/jails/{id}Setting a jail's action, use_custom_action, or custom_action.
POST /api/admin/cron-jobs, PUT or PATCH /api/admin/cron-jobs/{id}Creating a server cron job, or changing its command or user. A change of the schedule alone does not need it.
PATCH /api/admin/apache/settingsAny change of the MyApache Settings.
POST /api/admin/apache/profiles, PATCH /api/admin/apache/profiles/{id}Sending settings into a MyApache profile. Tags alone, or saving the current settings as a profile, do not need it.
POST /api/admin/apache/profiles/importLoading a MyApache profile.
PUT /api/admin/apache/includes/global/{stage}/{name}, PUT /api/admin/apache/includes/accounts/{id}/{domain}/{kind}/{name}Saving an Apache include file.
PUT /api/admin/php-versions/{id}/configurationChanging the PHP-FPM include, error_log, or pid setting of a PHP version. Its other settings do not need it.
POST /api/admin/php-versions/{id}/profiles/importImporting a PHP profile.
POST /api/admin/modsecurity/vendorsAdding a ModSecurity rule vendor. Updating, enabling, or disabling a vendor already on the list does not need it.
POST /api/admin/backup-destinations, PATCH /api/admin/backup-destinations/{id}Setting or changing the configuration of a custom rclone remote. Leaving it out keeps the stored one and does not need the permission, and the other destination types never need it.
POST /api/admin/server-backup/restoreRestoring the server configuration backup.
PUT /api/admin/acronis/connectionAny change of the Acronis connection.
POST /api/admin/acronis/server-file-restoresRestoring or downloading the server's own files from Acronis.
GET /api/admin/acronis/operations/{id}/downloadFetching a download of the server's own files, whoever started it. The download of an account needs no permission.
POST /api/hosting-accounts/migration-importImporting an account package that carries custom Apache directives. Nothing is imported when it is refused. A package without them does not need it.
PATCH /api/admin/api-keys/{id}Granting or revoking the permission itself on a key.

Where the table names fields, a field sent with the value it already has is not a change, so a client that sends back the object it read is not refused for it. The Acronis routes ask for the permission on every request they cover. The refusal names the permission and the fields it was asked for:

json
{
  "message": "This API key may not make writes that run commands as root on the server (custom_action). An administrator can allow them on the key with \"Allow writes that run commands as root\".",
  "required_permission": "allow_root_equivalent_writes",
  "fields": ["custom_action"]
}

The other 403 answers of these routes, such as a key without access to the endpoint, an address off the whitelist, or an expired license, keep their usual body with error and carry no required_permission.

An external migration run imports its accounts with its own credential, so the run carries the permission of whoever created it. A run created on the External Migrations page, or over the API with a key that holds the permission, imports accounts with their custom Apache directives. A run created with a key that does not hold it refuses such an account and names the permission. The key a hub creates on a node when it pairs the node holds the permission, because the hub moves accounts onto its nodes this way.

The permission over the API ​

The administrator's own keys and this permission are on the administrator API too:

Method and pathWhat it does
GET /api/admin/api-keysThe keys of the administrator who owns the calling key, as this page lists them, with allow_root_equivalent_writes. Neither the key nor its secret is returned.
GET /api/admin/api-keys/{id}One of those keys.
PATCH /api/admin/api-keys/{id}Grant or revoke the permission with {"allow_root_equivalent_writes": true} or false. The other fields of the key are returned for reading and ignored on a change.

Changing the permission, either way, needs the calling key to hold it, so a key without it cannot grant it to itself or to another key: it gets the refusal above with "fields": ["allow_root_equivalent_writes"]. Sending the value the key already has is not refused. Only an administrator's own keys are reachable, so the permission cannot be put on a reseller or client key. Each grant and revoke is written to the Activity Log with the id and name of the key that made it.

POST /api/admin/generate-sso-token returns a one-time link that signs in to the admin panel as an administrator. Since panel 1.9.5 it needs its own explicit grant on the key, also on a key with Allow all endpoints, because the session the link opens is not limited by the key's endpoint list or its permissions. Grant it only to automation you trust with the whole server, such as a billing module with an admin sign-in button. The administrator sign-in button of the AdminBolt WHMCS module uses this endpoint, so the key the module uses needs the grant after the upgrade.

Each link issued is written to the Activity Log as "Admin API: admin panel login link issued", with the id and name of the key, the administrator the link signs in as, and the calling address. The link itself is never recorded. When the entry cannot be written, the link is withdrawn and the call answers 500.

The LVE Manager sign-in token, POST /api/admin/cloudlinux/lvemanager/sso-token, needs its own explicit grant in the same way.

Existing keys after the upgrade to 1.9.5 ​

The upgrade to panel 1.9.5 leaves Allow writes that run commands as root off on every key that existed before, and no existing key gains the explicit grant for the sign-in link or the LVE Manager token. Two exceptions keep a hub working with its nodes:

  • The key a hub created on a node when it paired the node keeps the root writes it could make before, and on a node a hub manages, the upgrade gives that key the grant for the admin panel sign-in link, so the hub still opens the node's panel. A pairing made from now on creates the key with both.
  • A node connected with a key of its own, or whose pairing key was renamed, does not get the grant. When the hub then opens the node's panel, it says "The API key the hub uses on the node needs an explicit grant for this action." and how to add it: sign in to the node's panel, edit the key the hub uses, and select the endpoint under Endpoints that need an explicit grant. The node stays connected meanwhile.

Check every other key whose scripts make one of the writes above, or ask for a sign-in link or an LVE Manager token, and select the permission or the grant on the key's Edit form. Until then, those calls answer 403.