API Reference

Overview

The ZWPanel API is a REST API running on every ZWPanel node, used by the dashboard itself and available to external systems such as a billing platform. All endpoints are versioned under a single base path:

https://your-server:2088/api/v1

Requests and responses are JSON. Successful responses look like:

{ "status": "success", "data": { ... } }

Authentication

Every endpoint below (except /auth/login and /health) accepts either of two credentials:

An API key belongs to a specific admin or reseller account in the panel — the same way a WHM API token is tied to a specific root or reseller login. It is not a separate master credential: create (or designate) an admin or reseller user in ZWPanel for your billing integration, then use that account's key for every call. Whatever that account is allowed to do in the dashboard, the key can do via the API — including acting on behalf of its customers (see Acting on Behalf of a Customer).

The key is generated automatically when the account is created and returned once as api_key in the response (see Creating Accounts). You can also retrieve it later via GET /api/v1/users/:id as that admin/reseller.

curl https://your-server:2088/api/v1/health \
  -H "X-Api-Key: YOUR_API_KEY"

Creating Accounts

When a customer buys hosting, call this endpoint to create the hosting account. If a domain is supplied, ZWPanel runs full provisioning synchronously: OS user, home directory, PHP-FPM pool, Nginx vhost, DNS zone, and the plan's resource limits — the account is live when this call returns.

curl -X POST https://your-server:2088/api/v1/users \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "acmecorp",
    "password": "a-strong-generated-password",
    "email": "owner@acme.com",
    "domain": "acme.com",
    "plan_id": 1
  }'

{
  "status": "success",
  "data": {
    "id": 42,
    "username": "acmecorp",
    "email": "owner@acme.com",
    "role": "client",
    "api_key": "f3a1...own-key-for-this-account",
    "plan_id": 1
  }
}

Other account-management endpoints: GET /api/v1/users (list), GET /api/v1/users/:id, PUT /api/v1/users/:id, DELETE /api/v1/users/:id.

Acting on Behalf of a Customer

Your billing system holds one key, tied to one admin or reseller account, and uses it to manage every customer it's responsible for — the same way a WHM API token manages every account on the server. Which customer a given call applies to is decided one of two ways, depending on the endpoint:

Domain-scoped (Email, DNS)

The target domain is already part of the URL, e.g. /api/v1/email/acme.com/mailboxes. ZWPanel resolves which account owns that domain and checks that your key's account is allowed to touch it: an admin key may touch any domain; a reseller key only domains belonging to its own customers.

Account-scoped (Databases, FTP, Files)

These endpoints don't take a domain in the path, so add ?username=<customer-username> to act on that customer's account. Omit it and the call defaults to the key's own account.

curl "https://your-server:2088/api/v1/account/databases?username=acmecorp" \
  -H "X-Api-Key: YOUR_API_KEY"

Databases

All of the above accept ?username= as described in Acting on Behalf of a Customer.

curl -X POST "https://your-server:2088/api/v1/account/databases?username=acmecorp" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"db_name": "shop", "driver": "mysql"}'

{
  "status": "success",
  "data": {
    "id": 7,
    "db_name": "acmecorp_shop",
    "db_user": "acmecorp_4f2a1c",
    "db_password": "generated-strong-password",
    "driver": "mysql"
  }
}

Email

:domain is domain-scoped, as described in Acting on Behalf of a Customer — no ?username= needed.

curl -X POST https://your-server:2088/api/v1/email/acme.com/mailboxes \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "sales@acme.com", "password": "a-strong-password"}'

FTP Accounts

All of the above accept ?username= as described in Acting on Behalf of a Customer. Note: ftp_username must be unique across the entire server, not just within one account.

File Manager

All paths are resolved and sandboxed inside the target account's home directory — a path can't escape it even if crafted with ../. All of the above accept ?username= as described in Acting on Behalf of a Customer.

Errors

Errors share one shape:

{ "status": "error", "message": "Human-readable reason" }

Other Endpoints

The full panel API covers everything the dashboard itself uses — DNS zone records, hosting plans, WordPress/Softaculous installs, PHP version management, resource metrics, backups, and more — authenticated the same way described above. The sections above cover what a billing integration typically needs; reach out if your integration needs something beyond this list and we'll document it here.