Authentication and tokens
API tokens
Create a token under Account → API tokens (staff: Admin → Account → API tokens). The secret is shown once. Send it as a bearer token:
Authorization: Bearer pnl_…Tokens start with pnl_. Only a hash is stored, so a lost secret can’t be recovered; revoke the token and make a new one.
| Setting | Notes |
|---|---|
| Name | 1–64 characters, unique for your account |
| Scopes | What it may do. At least one. |
| IP allowlist | Addresses or CIDR ranges it may be used from. Empty means anywhere. |
| Expires | After 1–365 days, or never |
- An account can have up to 25 tokens.
- A token can never do more than its owner: it holds only scopes the owner has, and the owner’s role and permissions still apply on every call.
- A token stops working if its owner can’t sign in, and a customer’s tokens stop working while you switch off API tokens under Customer features.
- Tokens can’t be created or revoked during a support session.
- Creating a token asks for your password, and the account’s owner is emailed when one is created.
- Tokens made in a staff member’s own client area work only while the staff member is active, only from the addresses staff can sign in from, and are revoked when the staff member is disabled or removed.
- The token’s last use and address are shown on the tokens page, and actions are recorded in the audit log under the token’s name.
A request from outside the allowlist gets 403 ip_not_allowed. Behind a proxy, set PANEL_TRUSTED_PROXIES so the controller sees the caller’s real address.
Scopes
| Scope | Allows | Available to |
|---|---|---|
servers:read |
List servers, IPs, usage and jobs | Everyone |
servers:power |
Start, stop, restart and force off | Everyone |
servers:reinstall |
Wipe and reinstall from an image | Everyone |
servers:console |
Open VNC and serial console sessions | Everyone |
servers:rdns |
Change PTR records | Everyone |
servers:snapshots |
Take, restore and delete snapshots | Everyone |
servers:backups |
Change the schedule, back up and restore | Everyone |
servers:firewall |
Change firewall rules | Everyone |
servers:settings |
Hostname, rescue mode, ISO and boot order | Everyone |
ssh_keys:read |
List SSH keys | Everyone |
ssh_keys:write |
Add and remove SSH keys | Everyone |
dns:read |
List DNS zones and records | Customers, when DNS hosting is on |
dns:write |
Add, change and delete records, e.g. to get certificates | Customers, when DNS hosting is on |
networks:read |
Floating IPs and private networks | Customers, when either is on |
networks:write |
Move floating IPs for failover, change private networks | Customers, when either is on |
servers:create |
Provision servers for any customer when an order is paid | Staff |
servers:resize |
Upgrades, downgrades and extra IPv4 addresses | Staff |
servers:suspend |
Suspend and unsuspend servers for overdue invoices | Staff |
servers:terminate |
Destroy cancelled servers and free their addresses | Staff |
customers:read |
Look up customer accounts, their SSH keys and usage reports | Staff |
customers:write |
Create and update customer accounts from billing | Staff |
nodes:read |
Node health, usage and placement | Staff |
nodes:write |
Drain, resume and enroll nodes | Staff |
servers:move |
Move servers between nodes, empty nodes and cancel moves | Staff |
reseller:read |
Usage, quotas, locations, packages and customers | Resellers |
reseller:customers |
Sign up customers, with the client ID from your billing | Resellers |
reseller:servers |
Create, change, suspend and terminate customers’ servers | Resellers |
Presets
The token form has presets for common jobs:
| Preset | Scopes |
|---|---|
| Read-only | servers:read, ssh_keys:read |
| Automation | servers:read, servers:power, servers:rdns |
| Failover | servers:read, networks:read, networks:write |
| Full server control | Every servers:* scope above, ssh_keys:read, ssh_keys:write |
| Billing module (staff) | servers:read, servers:create, servers:resize, servers:suspend, servers:terminate, servers:power, servers:reinstall, customers:read, customers:write |
| Billing module (resellers) | reseller:read, reseller:customers, reseller:servers, servers:read, servers:power, servers:reinstall |
Calls only the panel can make
Some calls work only from a signed-in browser session, never with a token: changing passwords, two-factor and passkeys, managing API tokens and sessions, team access, notification settings, and most staff administration (settings, staff, packages, IP pools, templates, the audit log). A token gets 403 token_not_allowed for these.
Browser sessions
The panel itself signs in with an HttpOnly session cookie (panel_session), never a token in JavaScript or browser storage. Every request that changes something must send an X-CSRF-Token header matching the csrf_token cookie, and requests from other sites are refused. Token requests skip these checks.
- When the panel’s address is
https://, the cookies are called__Host-panel_sessionand__Host-csrf_token. Browsers only keep cookies with that prefix for this exact host, so another site on the same domain can’t set or replace them. On a plainhttp://test install they keep the names above. - A session ends after the inactivity time under Settings → Sign-in and sessions, and in any case 30 days after signing in.