REST API, command line and hooks

#Overview

The panel interface, the bipanel command and the AI assistant all use the same HTTP API. Almost anything you can do in the panel can therefore be scripted, and permission checks and the activity log behave the same whichever way you come in.

The API follows the same rules as the panel: the Community limit of 3 hosting accounts also applies when accounts are created through the API or the command line. See Pricing for edition differences.

#API tokens

A token acts on behalf of the person who created it, with that person's permissions; there are no separate scopes. A server administrator's token can manage the whole server, a reseller's token only the reseller's accounts, and a hosting account's token only that account. If a script needs narrower permissions, create the token as a user who has exactly those permissions.

#Creating a token

• Server Admin: the API Tokens page in the System group (server administrators and resellers).
• User panel: the API Tokens page in the Advanced group. If the package disables this feature, the page is hidden and the API rejects the request as well.

Give the token a name and optionally a lifetime between 1 and 3650 days; without one, the token stays valid until you delete it. Tokens start with bh_ and are shown only once, when created: the panel stores only a SHA-256 hash, and the list shows the first characters, last use and expiry. Team members cannot create tokens. Creating and deleting tokens is recorded in the activity log.

#When a token stops working

• It is deleted from the list or its lifetime ends.
• The account that owns it is suspended or deleted.
• The request comes from a blocked IP address (it is rejected even with a valid token).

#Authentication and requests

Send the token in the Authorization header. On a server installation the API is served on the panel's own addresses: port 2087 for Server Admin and port 2083 for the user panel (both reach the same API). On Docker/Railway, use the panel's public address.

curl -H "Authorization: Bearer $BIPANEL_TOKEN" https://server.example.com:2087/api/admin/accounts

#API Shell and the OpenAPI document

The API reference lives inside the panel and always matches the installed version. The API Shell page (in the System group of Server Admin and the Advanced group of the user panel) lists endpoints by area. Pick one, fill in the parameters and send the request with your session to see the status, timing and response, or copy it as a curl command that uses a token.

The machine-readable document is OpenAPI 3.1:

• /api/admin/openapi.json: the whole API. Endpoints reserved for the server administrator are hidden from resellers.
• /api/user/openapi.json: the account panel endpoints, without the features the package disables.

In the user panel the API Shell is a package feature; when the package disables it, it does not appear in the menu.

#The bipanel command-line tool

Server installations get the /usr/local/bin/bipanel command by default (listed among components as "Command-line tool", and removable). The Docker image ships it as well, for use inside the container. The command connects to the panel on 127.0.0.1 with a root token that the panel creates at start-up. On a server the token is kept in /etc/bipanel/cli.token (readable by root only), in containers in cli.token in the data directory, and it is accepted only on direct connections from the server itself.

$ sudo bipanel help
$ sudo bipanel account list --json
$ sudo bipanel service restart apache

#Command groups

There are also emergency commands for the firewall, country blocking and DDoS bans; see Security tools. For bipanel mcp, see AI assistant and MCP.

#Global options

Exit codes: 0 success, 1 error, 2 usage error.

#Regaining access

If you have lost the administrator password or the CLI token was deleted, these commands write to the panel database directly and work even while the panel is not running:

$ sudo bipanel admin reset-password
$ sudo bipanel admin reset-password admin --disable-2fa
$ sudo bipanel admin reset-token

A password reset closes open sessions and lifts IP bans. Without a password argument, a strong one is generated and printed.

#Hooks and plugins (Pro)

In the Pro edition, the Plugins & Hooks page in Server Admin lets you attach your own scripts to panel events.

#Hook scripts

There are three kinds of events: account and domain events (account created, suspended, domain added…), panel actions (account creation, database and email account creation, SSL requests, restores from backup…) and background events (SSL certificate installed, backup finished).

• A pre hook runs before the action. Exit code 0 lets it continue; exit code 1 stops it and shows the first lines of the output to the user as the reason. The time limit is at most 60 seconds.
• A post hook runs in the background after the action completes, with a time limit of up to 600 seconds (default 30).
• The script receives the event data as JSON on stdin, with the event name as its first argument, plus environment variables such as BIPANEL_EVENT, BIPANEL_USER, BIPANEL_DOMAIN and BIPANEL_ACTOR. Passwords are masked by default.
• On a server installation scripts run as root, so only files under /etc/bipanel/hooks or /usr/local/bipanel/hooks that are owned by root and not writable by others are accepted (in containers, the hooks directory in the data directory as well). Every run is logged with its output, duration and exit code, and you can test a hook with sample data.

#Plugins

A plugin is a .tar.gz package with a plugin.json at its root. It can add isolated pages to Server Admin and the user panel, bring its own hook scripts and run an optional backend service. Plugin pages call the panel with the permissions of the person viewing them, through a short-lived token valid for 15 minutes; that token cannot be used on session, password, token, 2FA, terminal, license or plugin management endpoints. The Plugins page in the user panel is switched on and off per package.

#Outgoing webhook notifications

To send monitoring alerts to an address as JSON, add a webhook channel on the Alerts & Notification Channels page (Pro; the email channel is also available in Community). Each request carries an HMAC-SHA256 signature in the X-Bipanel-Signature-256 header; verify it on the receiving side with the channel's secret. See Monitoring, limits and statistics for details.