# The SixPanel API

> Source: https://www.allsweb.com/sixpanel/docs/api
> Markdown for agents: https://www.allsweb.com/sixpanel/docs/api.md
> Publisher: AllsWeb (www.allsweb.com)

Part of: SixPanel documentation

**What this page is for.** Let a program — your billing system (WHMCS,
Blesta), AllsWeb, or a script of your own — make and manage accounts,
packages and websites on your server, the way WHM's API does. The program
holds an **API key**; it never needs your password or your panel's secret
address.

**You need**

- A key, made by you (the server's owner) or by a reseller for its own
  accounts. A key is shown **once**, when it is made. Copy it then.
- **SixPanel Pro+** for a key that makes or manages accounts or packages.
  A key that only reads and deploys **your own websites** is free.

---

## Make a key

**Settings → API keys → New key** (a reseller: its **Accounts** page, card
**API keys**):

1. **Name** — which program will hold it (`WHMCS`, `deploy-bot`). Activity
   names the key by it.
2. **Start from** — **A billing system (WHMCS, Blesta)**, **AllsWeb**,
   **Deploy my websites** or **Read only** ticks the scopes that job needs;
   **My own choice** lets you tick each one. Scopes marked **powerful** read
   secrets or sign people in.
3. **Whose things it reaches** — **its own**, **only the accounts and websites
   this key makes** (right for a billing system: it never sees anyone else),
   or **everything you reach**.
4. **Addresses it may be used from** — your billing server's address, one per
   line; empty means any.
5. **Expires** — in 30 or 90 days, a year (the default), two years, or never.
6. **Make the key**, and confirm it is you (your password, or your
   two-factor code). The key is shown **once**, with **Copy the key** and a
   ready `curl` line that tries it. The panel keeps only a hash of it: nobody,
   Tia included, can show it again. Lost it? Revoke it and make a new one.

The list shows each key's name and prefix (`spa_<id>_…`), what it may do,
whose things it reaches, when it expires and when it was last used, from
which address. **Revoke** stops a key at once: the program holding it is
refused from its next call. The same is at the server's command line
(below), and Tia can list and revoke keys for you.

## How a program calls it

Every call goes to `https://<your panel domain>/api/v1/…` and carries the key:

```bash
curl https://panel.example.com/api/v1/me \
  -H "Authorization: Bearer spa_…"
```

- The panel's secret entry code is **not** part of the address: the key is
  the credential. Without a valid key the address answers like any wrong
  address (a bare "not found"), so a stranger learns nothing.
- A server with no panel domain yet is reached at
  `https://<server address>:<panel port>/api/v1/…` (its certificate is
  self-signed, so `curl` needs `-k` there).
- Bodies are JSON (`Content-Type: application/json`), and so is every answer.
- A page of another website cannot use a key it found: a request from
  another site's page is refused.

## What a key can be limited to

| Limit | What it means |
|---|---|
| **Scopes** | What it may do, one family at a time (below). An endpoint needs exactly one scope. |
| **Reach** | Whose things it reaches: **own** (your own websites; a reseller's own account), **created** (only the accounts and websites this key made — right for a billing system), or **all** (everything its maker reaches). |
| **Addresses** | The addresses it may be used from — single addresses, ranges such as `203.0.113.0/24`, IPv6 addresses. Empty means any. |
| **Expiry** | One year unless you choose another date, or none. |

| Scope | Allows |
|---|---|
| `accounts:read` | list and read accounts, their package and what they use |
| `accounts:write` | make accounts, change them, suspend and unsuspend them, change their package |
| `accounts:password` | set an account's password |
| `accounts:sso` | make a one-time sign-in link for an account |
| `accounts:delete` | delete accounts (their websites moved, or backed up and deleted after seven days) and undo a delete inside those seven days |
| `accounts:move` | move user accounts to another reseller or to you, and make an account a reseller or a user again (your keys only, never a reseller's) |
| `packages:read` / `packages:write` | read packages / make, change and delete them |
| `websites:read` | list and read websites, and the **names** of their environment variables |
| `websites:write` | make websites |
| `websites:deploy` | deploy and restart websites |
| `websites:env` | read the **values** of a website's environment variables (its secrets) |
| `websites:transfer` | transfer websites between the accounts the key reaches (the previous owner's access closed) |
| `jobs:read` | follow jobs and read their log |
| `webhooks:read` / `webhooks:write` | list webhooks and read their deliveries / make, change, test and remove them (a new secret is answered once) |
| `usage:read` | the month's bandwidth, requests, CPU, memory and AI tokens of websites and accounts |
| `server:read` | the server summary (your keys only, never a reseller's) |

`accounts:delete`, `accounts:move` and `websites:transfer` are in no
starting point: a key deletes accounts, moves them between resellers or
moves websites only when the person making it ticks them. None of them can
be held by a key limited to **own**, and `accounts:move` only by your own
keys: on the Accounts page, too, only you change an account's reseller.

A key never does more than the person who made it. A reseller's key works
as that reseller: it sees itself and its own users, never another
reseller's accounts or your websites, and the users it makes are always its
own.

**What "only the accounts this key made" means**, on every endpoint:

- **Accounts**: the accounts the key made (or linked by setting their
  `externalId`), and what belongs to them. Suspending a reseller it made
  takes that reseller's users with it, as on the Accounts page.
- **Packages**: it reads the packages it may put an account on (your key:
  your packages and those of the resellers it made; a reseller's key: that
  reseller's), and changes or deletes **only the packages it made itself**.
  A package an earlier SixPanel made through the API is no key's: change it
  on the Accounts page, or with a key that reaches every account.
- **Websites**: the websites of the accounts it reaches. It makes a website
  only for one of those accounts — leaving `account` out is refused, with
  the field named — and never transfers one to you. A website it made stops
  being its own when it is transferred to an account the key does not
  reach. (A website of yours that such a key made with an earlier SixPanel
  stays its.)
- **Jobs, usage and webhooks**: the jobs it started and those of the
  websites it reaches; the usage of what it reaches; only the webhooks it
  made, and they hear only about the accounts it made and their websites.
- **The server summary** (`server:read`, your keys only) counts the whole
  server and names nobody.

Anything else answers exactly as something that does not exist (404).

A key stops working when it expires, when it is revoked, when its reseller
is deleted, and while its reseller is suspended.

**Replacing a key.** Make the new key with `replaces` set to the old key's
id (`POST /api/apikeys`, or **Replace the key** on the Accounts card for
WHMCS). It reaches everything the old key made, keeps the old key's name
when you give none, and takes over the old key's webhooks; the old key
keeps working for 24 hours, then expires. What the old key makes in those
24 hours is the new key's too. When a website is deleted, no key reaches
its id any more: another website made later with the same short name is
not the first one's key's. A key with reach **created**
should always be replaced this way: a key simply made again reaches
nothing the old one made. Setting an account's `externalId` with a key
makes that account the key's too, so a billing system that links an
existing account keeps reaching it.

## Answers and errors

A refused or failed call answers one shape, with a stable `code`:

```json
{ "error": { "code": "scope_missing", "message": "the API key \"WHMCS\" does not have the scope accounts:password …", "details": { "scope": "accounts:password" } }, "requestId": "…" }
```

| Code | When |
|---|---|
| `unauthorized`, `key_expired` | no key, an unknown or revoked key, an expired key |
| `ip_not_allowed`, `account_suspended` | used from an address not on its list; its reseller is suspended |
| `scope_missing`, `forbidden` | the key may not do this |
| `not_found` | it does not exist — or this key does not reach it (the same answer) |
| `validation`, `conflict`, `limit` | a field is wrong; it clashes with something there; the package has no room |
| `rate_limited` | too many calls this minute (see below) |
| `idempotency_key_reused`, `idempotency_in_progress` | see "Safe retries" |
| `promax_required` | making accounts needs SixPanel Pro+ |
| `confirm_required` | this needs a person's confirmation in the panel |
| `accept_required` | a delete or a transfer has warnings (`details.warnings`): read them, then send the call again with `"accept": true` |

A refused delete or transfer also says which check refused it in
`details.check` (for example `deleting`, `hasUsers`, `room`, `busy`, `from`).

Every answer says `Sixpanel-Api-Version: 1`. Inside version 1 changes only
add; anything removed comes as version 2, announced at least six months
before.

## Safe retries

Send an `Idempotency-Key` header (a UUID is usual) with any change. The
first answer is kept for 24 hours:

- the same request again gets the **same answer**, marked
  `Idempotent-Replayed: true` — no second account is made;
- the same key with a different body is refused (`422`), and nothing runs;
- the same key while the first request still runs is `409`.

A password the panel made is in the **first** answer only; a replay says
`passwordInFirstAnswer: true`. If it was lost, set a new one.

Give accounts and websites your own id with `externalId`. Making one again
with an `externalId` you already used answers the one already made
(`existing: true`), and `?externalId=` finds it. An `externalId` belongs to
whoever's key gave it: your keys see and find only the ids your keys set,
and a reseller's keys only the reseller's. So your billing system and a
reseller's own one can both number their services from 1 and never meet,
and one account can carry your id and its reseller's at the same time.

## Rate limits

Per key, per minute: **120 reads**, **30 changes**, and of the changes **10
that make something**. Every answer carries `RateLimit-Limit`,
`RateLimit-Remaining` and `RateLimit-Reset`; a refusal is `429` with
`Retry-After` in seconds.

## Provision from your billing system

What a hosting billing system (WHMCS, Blesta, your own) needs, in order:

1. **Make the key** — **Settings → API keys → New key**, start from **A
   billing system**, reach **only the accounts and websites this key makes**,
   and put your billing server's address in the address list. Copy the key
   into the billing system's server settings, with your panel's address.
2. **Make the packages** your plans sell on the **Accounts** page (or with
   `POST /packages`), and note each one's `id` (`GET /packages`).
3. **Map each billing action to one call** (below). Send an
   `Idempotency-Key` with every change and your own customer or service id as
   `externalId`, so a retry after a timeout never makes a second account.
4. **Hear about changes** instead of polling: add a webhook (below) for
   `account.*`, `usage.over_limit` and `job.finished`.
5. **Bill for use** at month end with `GET /usage?month=YYYY-MM` (or
   `&format=csv`).

| Billing action | Call |
|---|---|
| Create (a new order is paid) | `POST /accounts` with `package` and `externalId` |
| Suspend (unpaid) | `POST /accounts/{id}/suspend` with a `reason` (the account and its reseller read it) |
| Unsuspend (paid) | `POST /accounts/{id}/unsuspend` |
| Change package (upgrade, downgrade) | `POST /accounts/{id}/package` |
| Change password | `POST /accounts/{id}/password` |
| Log in to hosting | `POST /accounts/{id}/sso`, then send the browser to the `url` it answers |
| Find the account again | `GET /accounts?externalId=whmcs-1042` |
| Terminate | `DELETE /accounts/{id}` with `confirm` (its username), after `GET /accounts/{id}/delete/preview` — needs `accounts:delete` (below) |
| Undo a terminate that backed up its websites (within 7 days) | `POST /accounts/{id}/restore` |

```bash
KEY="spa_…"                       # the key, from your billing system's settings
API="https://panel.example.com/api/v1"

# which packages there are (their ids go in the billing system's product settings)
curl "$API/packages" -H "Authorization: Bearer $KEY"

# a new customer: an account on a package, its password made and answered once
curl -X POST "$API/accounts" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: 0b6f…" \
  -d '{"kind":"user","username":"acme","email":"it@acme.example","package":"<package id>","externalId":"whmcs-1042"}'

# unpaid: suspend it (its websites show the suspended page), and later lift it
curl -X POST "$API/accounts/<id>/suspend"   -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"reason":"invoice 1042"}'
curl -X POST "$API/accounts/<id>/unsuspend" -H "Authorization: Bearer $KEY"

# an upgrade
curl -X POST "$API/accounts/<id>/package" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"package":"<package id>"}'

# "log in to my hosting": a one-time sign-in link for the customer's browser
curl -X POST "$API/accounts/<id>/sso" -H "Authorization: Bearer $KEY"
# → {"url":"https://panel.example.com/api/v1/signin/…","expiresAt":"…","twofa":false}

# the customer changed their password in the billing system (leave "password" out to have one made)
curl -X POST "$API/accounts/<id>/password" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"password":"<the new password>"}'

# find the account again by your own id
curl "$API/accounts?externalId=whmcs-1042" -H "Authorization: Bearer $KEY"

# month end: what every account this key made used, as a CSV for invoicing
curl "$API/usage?month=2026-11&format=csv" -H "Authorization: Bearer $KEY" -o usage-2026-11.csv

# be told at once instead of asking: a webhook (its secret is in this answer only)
curl -X POST "$API/webhooks" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://billing.example.com/sixpanel-hook","events":["account.suspended","account.unsuspended","usage.over_limit","job.finished"]}'
```

The sign-in link works **once**, within **60 seconds**, in a browser. It
signs the customer into their own account — never yours. An account with
two-factor on still types its own code. `{"app":"site:<website id>"}` or
`{"app":"files:<website id>"}` opens one of its websites.

## Delete, restore and transfer

These do what the **Accounts** page's **Delete** and **Restore**, and a
website's **Transfer**, do, with the same checks and the same refusals.
Each has a preview that changes nothing; read it, then make the call that
does it. The call asks again everything the preview checked, and asks for
the name typed, as the page does: the account's username, or the website's
short name. A reseller's key reaches its own users only, and moves a
website only between itself and its users.

**Delete an account** (`accounts:delete`). The choices are the page's:

| Field | Values |
|---|---|
| `sites` | `move` (the default: its websites go to its reseller — or to you with `sitesTo: "owner"` — with its FTP users, passwords and webhook secret closed; the account is gone at once, with no Restore) or `delete` (a full backup, proved first; the account is held, suspended, for seven days, then its websites are deleted) |
| `users` | a reseller that has users must say what happens to them: `owner` (your own users), `reseller` with `usersTo` (another reseller's id), or `delete` |
| `usersPackage` | a package for the users that move |
| `target` | where the backup goes (a backup destination's id; your keys only) |
| `accept` | `true` once you have read the preview's warnings |
| `confirm` | the account's username |

```bash
# 1. what it would do (nothing changes)
curl "$API/accounts/<id>/delete/preview?sites=delete" -H "Authorization: Bearer $KEY"
# → {"account":{"id":"…","username":"acme","kind":"user"},"ok":true,"refusal":null,"needsAccept":false,
#    "websites":[{"slug":"acme-shop","action":"delete","databases":["acme_shop"],…}],
#    "backup":{"target":{"id":"local","name":"This server (local disk)","type":"local"},…},
#    "grace":{"days":7,"until":"2026-11-21T…"},"checks":[…],…}

# 2. do it
curl -X DELETE "$API/accounts/<id>" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: 4d2a…" \
  -d '{"sites":"delete","confirm":"acme"}'
# → 202 {"mode":"delete","websites":1,"users":0,"until":"2026-11-21T…","job":{"id":"…","status":"queued","url":"/api/v1/jobs/…"},…}
# with "sites":"move" it answers "mode":"move", "to":"reseller" or "owner", and one job per website in "jobs"

# 3. changed your mind within the seven days
curl -X POST "$API/accounts/<id>/restore" -H "Authorization: Bearer $KEY"
# → {"account":{…,"status":"active"},"accounts":1,"websites":1,"job":{…}}
```

| Refusal | Answer |
|---|---|
| no `confirm`, or not its username | `400 validation`, `details.field: "confirm"`; nothing changes |
| a choice that is not one (`sites: "burn"`) | `400 validation` |
| it is being deleted already | `409 conflict`, `details.check: "deleting"` — a second terminate is safe |
| a reseller with users and no `users` | `409 conflict`, `details.check: "hasUsers"`, `details.users` names them |
| the reseller its users go to has no room | `403 limit`, `details.check: "room"` |
| one of its websites has a job running | `409 conflict`, `details.check: "busy"` |
| the preview has warnings | `409 accept_required`, `details.warnings` |
| restore of an account that is not being deleted | `409 conflict` |
| a reseller's key restoring a delete you began | `403 forbidden` |
| an account the key does not reach | `404 not_found` |
| a key that reaches only what it made, `users: "delete"`, and a user of that reseller the key did not make | `403 forbidden`, `details.field: "users"` — send them to `owner` or a reseller it made instead |

**Move a user to another reseller, or to you** (`accounts:move`, your keys
only). The Accounts page's **Change its reseller**: the preview first,
then the move. Its websites stay where they are and keep serving; its old
reseller's "log in as" sessions into it end, and a suspension that came
from its old reseller is lifted (yours stays).

| Field | Values |
|---|---|
| `to` | the reseller it goes to (its id or username), or `owner` |
| `package` | a package id: one of that reseller's user packages, or one of yours; `null` (in the preview: empty) for none. Left out, it keeps its own — refused when that package was its old reseller's |
| `from` | optional: whose it was when you read the preview (the reseller's id, or `owner`) — an account that moved since is refused |

```bash
# 1. what it would do (nothing changes)
curl "$API/accounts/<id>/move/preview?to=owner&package=<your package id>" -H "Authorization: Bearer $KEY"
# → {"account":{"id":"…","username":"acme"},"from":"agency","to":"owner","ok":true,"refusal":null,
#    "package":{"from":"Agency Basic","to":"Full"},"websites":["acme-shop"],"projects":[],"checks":[…],…}

# 2. do it
curl -X POST "$API/accounts/<id>/move" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: 7c1e…" \
  -d '{"to":"owner","package":"<your package id>","from":"<agency id>"}'
# → {"account":{…,"reseller":null},"websites":1,"job":{"id":"…","status":"queued","url":"/api/v1/jobs/…"}}
```

**Reseller rights** (`accounts:move`, your keys only).
`POST /accounts/{id}/reseller` makes one of your own user accounts a
reseller (`package`: one of your reseller packages, or none);
`DELETE /accounts/{id}/reseller` makes a reseller that has no users one of
your user accounts again (`package`: one of your user packages, or none) and
removes its own packages. Either way every session of that account ends,
and its next sign-in sees what it is now. Its API keys stop when it is no
longer a reseller.

| Refusal | Answer |
|---|---|
| a key without `accounts:move` | `403 scope_missing` |
| a reseller's key (it can never be made with `accounts:move`; one that holds it anyway) | `403 forbidden` |
| an account, a reseller or a package the key does not reach, or that is not there | `404 not_found`, `details.field` `to` or `package` when it is one of those |
| no `to` | `400 validation`, `details.field: "to"` |
| its package was its old reseller's and no other is given | `409 conflict`, `details.check: "package"` — pick one of the new reseller's packages, or one of yours |
| the new reseller's package has no room | `403 limit`, `details.check: "room"`, `details.resource` |
| the new reseller is suspended or being deleted | `409 conflict`, `details.check: "suspended"` |
| a reseller to be moved, or a user to where it already is | `409 conflict`, `details.check` `kind` or `same` |
| it is being deleted | `409 conflict`, `details.check: "deleting"` — Restore it first |
| `from` is not whose it is now | `409 conflict`, `details.check: "from"` |
| make a reseller of a reseller's user, or of a reseller | `409 conflict` — move it to you first |
| reseller rights taken from a reseller that has users | `409 conflict`, `details.check: "hasUsers"`, `details.users` names them |
| a package of the wrong kind | `400 validation` |

A key that reaches only what it made moves only the users it made, and
only to a reseller it made or to you.

**Transfer a website** (`websites:transfer`). `to` is an account the key
reaches, by its id or username, or `owner` (your keys only).

```bash
# 1. what it would do: every check with its numbers, what moves, what is closed for the previous owner
curl "$API/websites/<website id>/transfer/preview?to=acme" -H "Authorization: Bearer $KEY"
# → {"website":{"slug":"acme-shop","account":"<from id>",…},"from":{…},"to":{"username":"acme",…},"ok":true,
#    "checks":[{"key":"room","ok":true,"text":"…"}],"closes":{"applies":true,"ftpUsers":["…"],"envKeys":["APP_KEY",…]},"downtime":"none"}

# 2. do it ("from" is whose it was in the preview: a website that changed hands since is refused)
curl -X POST "$API/websites/<website id>/transfer" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: 91fe…" \
  -d '{"to":"acme","confirm":"acme-shop","from":"<from id>"}'
# → 202 {"website":{…,"account":"<acme's id>"},"job":{"id":"…","status":"queued","url":"/api/v1/jobs/…"},"closed":true,"removedSshKeys":[],"repoToken":null}
```

`closeAccess: false` keeps the previous owner's FTP users and passwords (for
two accounts of the same customer); `clearAiHistory`, `removeSshKeys` (key
ids, or `true`) and `removeRepoToken` are the dialog's ticks.

| Refusal | Answer |
|---|---|
| no `to` | `400 validation`, `details.field: "to"` |
| no `confirm`, or not its short name | `400 validation`, `details.field: "confirm"` |
| it changed hands since the preview | `409 conflict`, `details.check: "from"` |
| the receiving package has no room | `403 limit`, `details.check: "room"`, `details.resource` |
| it already belongs to that account | `409 conflict`, `details.check: "same"` |
| a job or an AI Coding turn is running on it, it has staging sites, the receiver is suspended | `409 conflict`, `details.check` names it |
| the preview has warnings | `409 accept_required`, `details.warnings` |
| an account or website the key does not reach (a reseller's key: also `owner`) | `404 not_found` |

Every delete, restore and transfer is on the **Activity** page, named by
the key that made it.

## WHMCS

SixPanel has its own WHMCS server module. Once it is set up, WHMCS makes
the account when a customer pays, suspends it when an invoice is overdue,
lifts the suspension when it is paid, changes its package on an upgrade,
and sets its password. **Log in to SixPanel** in WHMCS's client area signs
the customer straight into their own account.

**Terminate deletes only when you let it.** WHMCS deletes an account on
**Terminate** (as the product's **On terminate** settings say) only when
its key has **Let WHMCS delete accounts** ticked (the scope
`accounts:delete`). Without the tick — the default — the module suspends
the account ("WHMCS: terminated"), so the cancelled customer's
websites, and any 6amMart project it holds, stop
serving, and WHMCS shows that the account still has to be
deleted on the **Accounts** page, or the key replaced with the tick.
**Unsuspend** in WHMCS lifts it again. An account deleted with **Back up,
then delete** can be put back with **Restore** on the **Accounts** page for
seven days; one whose websites were kept is gone at once.

You need WHMCS 8 or later with PHP 7.4 or later (with curl), SixPanel Pro+,
and a **panel domain** (`panel.example.com`): WHMCS checks the certificate,
and a server's bare address has a self-signed one.

1. **Download the module.** **Accounts** → **Sell accounts from WHMCS** →
   **Download the WHMCS module**. A reseller has the same button for its own
   users.
2. **Make a key for it.** On the same card, press **Make a key for
   WHMCS**. It holds exactly what the module uses (`accounts:read`,
   `accounts:write`, `accounts:password`, `accounts:sso`, `packages:read`,
   and `accounts:delete` when you tick **Let WHMCS delete accounts**).
   Keep **Only the accounts WHMCS makes or links**: the key then reaches
   the accounts WHMCS made or linked and nothing else, so a stolen WHMCS
   config cannot sign into, or set the password of, any other account on
   the server. Choose **Every account** only to link accounts you made
   before WHMCS (below), then replace it with a narrow one. Expiry
   **Never** keeps WHMCS working; add WHMCS's IP address if it is fixed.
   Copy the key: it is shown once.
3. **Upload it.** Copy the zip's `modules` folder into your WHMCS folder, so
   that `modules/servers/sixpanel/sixpanel.php` is there.
4. **Add the server.** In WHMCS: **System Settings** → **Servers** → **Add
   New Server**. Module **SixPanel**, Hostname your panel domain, **Access
   Hash** the key. Press **Test Connection**: it names exactly what to fix,
   such as a scope the key lacks.
5. **Make a product.** **Products/Services** → the product → **Module
   Settings** → Module Name **SixPanel**:

| Setting | What it does |
|---|---|
| **Package** | The SixPanel package, by its name or its id. |
| **Account type** | **User**, or **Reseller** (only with a key you made, not a reseller's). |
| **On terminate, its websites** | What a terminate does when the key may delete: **Back up, then delete them after 7 days** (the default; **Restore** on the Accounts page until then), or **Keep them**, moved to the reseller or to you. Without **Let WHMCS delete accounts** a terminate suspends the account instead (above). |
| **On terminate, a reseller's users** | The same, for a reseller's users: **Keep them** as your own users (the default), or delete them too. |
| **Billing id prefix** | `whmcs` unless two WHMCS installs share this server. |

**How WHMCS finds the account.** The module stores the service's billing id
(`whmcs-<service id>`) on the SixPanel account, and finds the account by it,
never by the username alone. So an order WHMCS retries never makes a
second account, and terminating a service can never reach an account you
made by hand that happens to share its name. An account you made before
the module is joined to its service on purpose: set the service's username
to the account's, then press **Link to SixPanel account** on the service in
WHMCS. An account already joined to another service is never taken. The
key must reach that account: use a key with **Every account** for the
link, then **Replace the key** with a narrow one. A linked account stays
with WHMCS's key from then on.

**Replacing the key.** Press **Replace the key** beside it on the
**Accounts** card. The new key reaches every account the old one reached,
and the old one keeps working for 24 hours, so WHMCS does not stop while
you paste the new key into the server's **Access Hash**. An order WHMCS
provisions with the old key in that time is reached by the new key too. A key you simply
make again reaches none of the accounts WHMCS made, and Test Connection
cannot tell, because a key that reaches nothing yet is a valid key.
**Revoke** stops a key at once. A revoked or mistyped key makes WHMCS say
"SixPanel did not let this call in", and each WHMCS run stops after the
first refusal, so it never locks WHMCS's address out of the panel.

**Two billing systems on one server.** A billing id belongs to whoever's
key gave it. Your WHMCS and a reseller's own WHMCS can both use the prefix
`whmcs` and both number services from 1: neither ever finds, suspends or
signs into the other's customers.

**What it reports.** WHMCS's daily usage update reads each account's disk
use and its package's disk limit. Bandwidth is not reported yet.

**What it records.** Every call is on SixPanel's **Activity** page under
**An API key**, and in WHMCS's **Module Log**, with the key and every
password masked.

## Every endpoint

| Endpoint | Scope | Does |
|---|---|---|
| `GET /me` | — | this key: its scopes, reach, expiry, limits |
| `GET /accounts` | `accounts:read` | list (`kind`, `status`, `reseller`, `externalId`, `q`, `limit`, `cursor`) |
| `POST /accounts` | `accounts:write` | make one (password optional: one is made and answered once) |
| `GET /accounts/{id}` | `accounts:read` | one account, its limits, users and websites |
| `PATCH /accounts/{id}` | `accounts:write` | name, email, note, package, externalId |
| `POST /accounts/{id}/suspend` · `/unsuspend` | `accounts:write` | suspend (a reseller's users with it) / lift it |
| `POST /accounts/{id}/package` | `accounts:write` | change its package |
| `POST /accounts/{id}/password` | `accounts:password` | set a password (or have one made); its sessions end |
| `POST /accounts/{id}/sso` | `accounts:sso` | a one-time sign-in link |
| `GET /accounts/{id}/usage` | `accounts:read` | what it uses against its package |
| `GET /accounts/{id}/delete/preview` | `accounts:delete` | what deleting it would do, for the choices given — nothing changes |
| `DELETE /accounts/{id}` | `accounts:delete` | delete it (`confirm`: its username) — answers its job |
| `POST /accounts/{id}/restore` | `accounts:delete` | undo its delete within the seven days |
| `GET /accounts/{id}/move/preview?to=` | `accounts:move` | what moving a user to another reseller (or to you) would do — nothing changes |
| `POST /accounts/{id}/move` | `accounts:move` | move it (`to`, `package`, `from`) — answers the job that writes its limits again |
| `POST /accounts/{id}/reseller` · `DELETE /accounts/{id}/reseller` | `accounts:move` | make one of your users a reseller / a reseller with no users a user again (`package`) |
| `GET /packages` · `GET /packages/{id}` | `packages:read` | packages |
| `POST /packages` · `PATCH` · `DELETE /packages/{id}` | `packages:write` | make, change (a `PATCH` changes only the limits and switches it names), delete (one in use is not deleted) |
| `GET /websites` · `GET /websites/{id}` | `websites:read` | websites (`account`, `kind`, `externalId`) |
| `POST /websites` | `websites:write` | make one — yours, or an account's (`account`) — answers its job |
| `POST /websites/{id}/deploy` | `websites:deploy` | deploy from its git repository — answers its job |
| `POST /websites/{id}/restart` | `websites:deploy` | restart its app (Node.js, Python, Java) |
| `GET /websites/{id}/env` | `websites:read` | the **names** of its environment variables |
| `GET /websites/{id}/env/values` | `websites:env` | their values |
| `GET /websites/{id}/transfer/preview?to=` | `websites:transfer` | what transferring it would do — nothing changes |
| `POST /websites/{id}/transfer` | `websites:transfer` | transfer it (`to`, `confirm`: its short name) — answers its job |
| `GET /jobs/{id}` · `GET /jobs/{id}/log?tail=100` | `jobs:read` | follow a job; the last lines of its log (a reseller's or a user's key reads a job as their own pages show it: a copy kept before an import by its file name, without the owner's Terminal line) |
| `GET /webhooks` · `GET /webhooks/{id}` | `webhooks:read` | the webhooks this key made (all of its holder's with reach `all`), never a secret |
| `POST /webhooks` | `webhooks:write` | add one: `url` (https), `events` (or `["*"]`), `description` — its `secret` is answered once |
| `PATCH /webhooks/{id}` · `DELETE /webhooks/{id}` | `webhooks:write` | change its address, events or `enabled`; remove it |
| `POST /webhooks/{id}/roll` | `webhooks:write` | a new secret, answered once; the old one signs beside it for 24 hours |
| `POST /webhooks/{id}/test` | `webhooks:write` | send it a `ping` now |
| `GET /webhooks/{id}/deliveries` · `POST /webhooks/deliveries/{id}/retry` | `webhooks:read` · `webhooks:write` | its last 30 days of deliveries (`state`, `limit`); send one again |
| `GET /usage?month=YYYY-MM` | `usage:read` | every account it reaches, with the month's bandwidth, requests, CPU, memory, AI tokens and `overLimit`; `format=csv` answers a CSV file |
| `GET /accounts/{id}/usage/month` | `usage:read` | one account's month, with each of its websites (a reseller: also its family's total) |
| `GET /websites/{id}/usage` | `usage:read` | one website's bytes and requests in the month |
| `GET /server` | `server:read` | version, machine, load, counts |

Long work answers `202` with `{ "job": { "id", "status", "url" } }`; follow
it at `GET /jobs/{id}`.

```bash
# who this key is, and what it may do
curl "$API/me" -H "Authorization: Bearer $KEY"

# a website for an account, from its git repository (answers its job)
curl -X POST "$API/websites" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1e…" \
  -d '{"kind":"node","name":"Acme shop","account":"<account id>","domain":"shop.acme.example","repo":"https://github.com/acme/shop.git","branch":"main","externalId":"whmcs-1042-web"}'

# follow the job until "status" is "ok" or "failed", and read the end of its log
curl "$API/jobs/<job id>" -H "Authorization: Bearer $KEY"
curl "$API/jobs/<job id>/log?tail=50" -H "Authorization: Bearer $KEY"

# deploy it again after a push, and restart its app
curl -X POST "$API/websites/<website id>/deploy" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{}'
curl -X POST "$API/websites/<website id>/restart" -H "Authorization: Bearer $KEY"

# a new package for a plan you sell (limits in MB and per cent)
curl -X POST "$API/packages" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Starter","kind":"user","limits":{"websites":3,"diskMb":10240,"bandwidthMb":102400}}'
```

The machine-readable description of all of it, for tools that read
OpenAPI 3.1, is at `https://panel.example.com/api/v1/openapi.json`. Send
your key with it, like any other call: without one (and without the
panel's entry code) the address answers a bare 404, as every API address
does.

## Webhooks

A webhook is an address SixPanel sends an event to the moment something
happens, so your billing system does not have to ask every minute. You add
them under **Settings → Webhooks** (a reseller: on its Accounts page, when its
package has **Webhooks** ticked), or through the API. Up to 10 each.

- **https only, public addresses only.** The address is looked up when you add
  it and again before every delivery; one that leads to this server, a private
  network or a cloud metadata address is refused, and a delivery goes to
  exactly the address that was checked. A redirect is never followed.
- **The secret is shown once**, when the webhook is added or given a new
  secret. A new secret and the old one both sign for 24 hours, so you can
  change your receiver without missing a delivery.

Every delivery is a `POST` with a JSON body
`{ "id": "evt_…", "type": "account.suspended", "createdAt": "…", "data": { … } }`
and these headers: `Sixpanel-Event`, `Sixpanel-Event-Id`, `Sixpanel-Delivery`
and `Sixpanel-Signature: t=<unix seconds>,v1=<hex>` (two `v1=` while a secret
rolls). Check it like this:

```js
const crypto = require('node:crypto');
function fromSixPanel(rawBody, header, secret) {
  const t = Number((/(?:^|,)t=(\d+)/.exec(header) || [])[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes: refuse
  const want = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return [...header.matchAll(/v1=([0-9a-f]{64})/g)].some(([, got]) =>
    crypto.timingSafeEqual(Buffer.from(got, 'hex'), Buffer.from(want, 'hex')));
}
```

Use the body exactly as it arrived (not parsed and written again), answer
`2xx` within 10 seconds, and do the work afterwards. Anything else — no
answer, a 3xx, 4xx or 5xx — is tried again after 1 and 5 minutes, half an
hour, 2, 4, 8 and 12 hours and then a day twice: ten tries over three days.
The `id` is the same in every try and in **Send again**, so keep the ids you
have handled and ignore one you have seen. Deliveries are kept 30 days, with
each try's answer, on the webhook's **Deliveries**.

| Event | When |
|---|---|
| `account.created` · `account.updated` | an account was made; its name, email, package or kind changed (`data.changes`) |
| `account.suspended` · `account.unsuspended` | suspended (a reseller's users each get their own) or lifted |
| `account.moved` | a user moved to another reseller or to you |
| `account.deleting` · `account.restored` · `account.deleted` | a delete with its grace days began, was undone, or ended |
| `website.created` · `website.transferred` · `website.deleted` | a website was made, moved to another account, or deleted |
| `deploy.started` · `deploy.finished` | a deploy, build or rollback began or ended (`data.job.status`: `ok` or `failed`) |
| `job.finished` | any job about a website or an account ended |
| `usage.over_limit` | an account went over its package's monthly bandwidth (`usedBytes`, `limitBytes`, `suspended`) — once a month |
| `ping` | **Send a test** |

The owner's webhooks hear every event on the server; a reseller's only those
about itself, its users and their websites. A webhook made by an API key is
never wider than that key: it hears `account.created` and `website.created`
of what that key makes, and stops when the key is revoked or expires (the
Webhooks list says which). Each body
carries your `externalId` for the account or website, when you gave one.

## Usage

`GET /usage` answers the month (`?month=2026-11`, default this month) for
every account the key reaches; `?format=csv` answers the same as a CSV file.
Bandwidth and requests come from each website's own visit log, read by
offset every 10 minutes; CPU seconds and memory from the account's slice
(`null` for an account without process limits); AI is the tokens AI Coding
counted, by model — the panel does not price them. The Accounts manual
chapter says how each is measured and what happens over the limit.

## From the server's command line

At an SSH prompt on the server (as root, or with `sudo`), the same keys and
webhooks are one command away — the way in when the panel is out of reach,
and the way to script it:

```bash
sudo sixpanel api-key create --name WHMCS --preset billing --ip 203.0.113.10
sudo sixpanel api-key list
sudo sixpanel api-key revoke <id>        # or the whole key
sudo sixpanel webhook list
sudo sixpanel webhook test <id>
```

- `create` makes one of **your** keys (a reseller makes its own in the panel)
  and prints it **once**, alone on the first line. `--preset` is `billing`,
  `allsweb`, `deploy` or `readonly`; or name each scope with `--scope`
  (repeat it), and the reach with `--reach own|created|all`.
  `--expires-days 90` or `never`; one year when you say nothing. A key that
  reaches accounts needs SixPanel Pro+, as in the panel.
- `revoke` works even while the panel is stopped: the command stops and starts
  it once, and tells you first.
- `--json` on `list` answers JSON for a script. `sixpanel help api-key` has
  every option.

## Tia and API keys

Tia can **list** the keys (name, prefix, what each may do, when it expires
and was last used) and **revoke** one, on a card you approve — the quick way
to stop a key you think leaked. She never **makes** a key and never sees one:
the panel keeps only a hash of each key, and a key pasted into a chat reaches
her with its secret hidden (`spa_<id>_****`).

## What you see in the panel

Every change a key makes, every read of a website's secrets and every
refusal is on the **Activity** page under **An API key**, with the key's
name. Deploys and jobs it started say the same.

A server migration does not carry keys to the new server: make them again
there and give your billing system the new ones.
