Developers

Automate ZoPanel: the provisioning API with tokens and idempotency keys, signed webhooks and hook scripts, billing modules, the CLI and llms.txt.

Updated Oct 7, 2026

ZoPanel is built to be driven by other software. Billing systems create and suspend accounts through the provisioning API, your own tools react to events through signed webhooks, and administrators script the server with the command line. This page is the starting point; the details are in the documentation.

Provisioning API

The provisioning API (/api/v1) creates and manages hosting accounts on a ZoPanel server. It is the same API the WHMCS, Blesta, HostBill and Paymenter modules use, so anything they do, your own CMS or billing code can do too.

• Accounts are addressed by their username, packages by their name. Your side does not need to store any ZoPanel IDs.
• Lifecycle: create (optionally with the first website, issued with SSL when the domain already points to the server), suspend, unsuspend, change package, set password, terminate.
• Packages: list the packages you can sell, or push your own plans with PUT /api/v1/packages/{name}.
• Single sign-on: POST /api/v1/accounts/{username}/login returns a link that is valid once, for 60 seconds, for a "Log in to control panel" button in your client area.
• Usage: disk and monthly bandwidth for every account you manage.

T="Authorization: Bearer zpat_xxx"; P=https://panel.example.com:8888/api/v1

# Push a plan
curl -X PUT -H "$T" \
  -d '{"max_sites":3,"disk_mb":10240,"memory_mb":1024,"cpu_percent":100,"sftp":true}' \
  $P/packages/Starter

# Sell it: create the account and its first website
curl -X POST -H "$T" -H "Idempotency-Key: order-1042-create" \
  -d '{"username":"shop1","password":"S3cure-Pass-1","email":"owner@shop1.example","package":"Starter","domain":"shop1.example"}' \
  $P/accounts

# Unpaid invoice, then paid
curl -X POST -H "$T" $P/accounts/shop1/suspend
curl -X POST -H "$T" $P/accounts/shop1/unsuspend

Errors come back as JSON ({"error": "…"}) with a meaningful status: 400 invalid input, 402 license limit reached, 403 not allowed for this token, 404 unknown account, 429 too many requests.

Full reference: Provisioning API.

Authentication with API tokens

1. In ZoPanel, open My account → API tokens.
2. Create a token with the permission Provisioning only, and limit it to the IP address of your billing server.
3. Send it with every request: Authorization: Bearer zpat_….

What a token can reach depends on who owns it. An administrator's token sells the administrator's packages and sees every hosting account; a reseller's token sells only that reseller's packages, sees only their customers, and stays within the reseller's own plan. A provisioning token cannot reach anything else in the panel: no server settings, no files, no terminal. Tokens are revoked when their owner changes password or 2FA, and creating one requires the owner's password.

API tokens need a paid license.

Idempotency keys and rate limits

Networks fail, and billing systems retry. Send a unique Idempotency-Key header with every POST, PUT and DELETE (for example whmcs-create-<service id>):

• repeating a request with the same key within 24 hours returns the first answer, with the header Idempotent-Replayed: true, instead of doing the work again, so a retry after a timeout never creates an account twice;
• while the first request is still running, a repeat gets 409;
• server errors (5xx) are not stored, so those requests can simply be retried.

Each token may make 1,200 requests a minute. Above that the answer is 429 with Retry-After: 60.

Webhooks and event hooks

ZoPanel publishes events when something changes on the server:

account.created, account.deleted, account.suspended, account.unsuspended, site.created, site.deleted, ssl.issued, database.created, database.deleted, mail.domain_created, mail.mailbox_created, backup.completed.

Webhooks. An administrator adds webhook URLs on the Hooks page, each with its own secret and an optional list of events. ZoPanel sends a JSON POST:

{"event": "account.created", "time": 1759795200, "server": "web1.example.com", "data": { … }}

with these headers:

Verify the signature on the raw body before trusting the payload, and compare it in constant time. A failed delivery is retried twice (after 5 and 30 seconds). The Hooks page shows recent deliveries and can send a test event. Event payloads never contain secrets.

Hook scripts. For automation on the server itself, executables in /etc/zopanel/hooks/<event>.d/ run after each event, with the event JSON on standard input. Only root can install them over SSH, never through the panel: a script runs only if it and its folder are owned by root and not writable by group or others.

Billing modules

Ready-made modules cover create (with the order's domain as the first website), suspend and unsuspend, terminate, change package and single sign-on; where the billing system supports it, they also report usage and change passwords.

Each package has a README with install steps. A reseller can connect their own billing system with a token from their reseller account. See Integrations.

Command line

Administrators manage the server with zopanel ctl over SSH: info (version, server ID, license plan), reset-password, disable-2fa, allow-ip --clear when an IP allowlist locks you out, rebuild to regenerate web server and PHP configuration from the panel database, doctor for a health check, support-bundle, and dr-restore for disaster recovery. zopanel update and zopanel rollback install and undo updates. Reference: Command line.

llms.txt for AI assistants

If you use an AI assistant or coding agent with ZoPanel, point it at:

• /llms.txt: an index of the documentation with one-line summaries;
• /llms-full.txt: the whole documentation in one Markdown file.

Both follow the llms.txt convention and are generated from the same pages you read here, so they stay current.

OpenAPI specification

An OpenAPI 3.0 description of the provisioning API v1 (provisioning-openapi.yaml) is maintained with the API and covers the endpoints, package fields, errors and authentication described above. Use it to generate a client or to import the API into your API tool. The panel's other internal endpoints, used by its own interface, are not a public API and may change between releases; build integrations on /api/v1, webhooks and hook scripts.

Need help?

Questions about an integration, or a feature your automation needs: open a ticket with the category Technical on the support page.