API keys

Give a script or another service its own way in.

License required

API keys need the API Keys license feature. An administrator also has to turn on Allow API Keys at Admin > Settings > Features.

An API key lets an automation or a third-party integration use BadgerPanel without the login credentials of a user. You can restrict a key to specific permissions and to specific IP addresses.

Navigate to Admin > Management > API Keys.

The key list

Column	Description
Name	The key name and the description.
Key	The key prefix, for example bp_exampleprefix.... A copy button copies the prefix.
Permissions	The number of granted permissions.
Last Used	The date of the last request with the key, or Never.
Status	A pill that reads Active or Inactive. Click the pill to change the state.
Actions	An eye icon to open the key, and a bin icon to delete it.

Creating a key

1. Navigate to Admin > Management > API Keys and click Create API Key.
2. Enter a Name, for example "Production API".
3. Enter a Description to record the purpose of the key. This field is optional.
4. Set an Expiration Date. Leave it empty for a key that does not expire.
5. Add IP Restrictions. Enter an IP address or a CIDR range such as 192.168.1.0/24, then click the plus button. Each entry becomes a chip. An empty list permits every address.
6. Select the Permissions. Grant only the permissions that the integration needs.
7. Click Create API Key.

The panel then shows the full secret one time. Copy it and store it safely. After you click Done, the panel shows only the prefix.

Editing a key

Click the eye icon on a row to open the key. You can change the name, the description, the expiration date, the IP restrictions, and the permissions. Click Save Changes.

You cannot read the secret again. Create a new key when you lose one.

Turning a key off

Click the Active pill on the row to make the key inactive. The panel rejects an inactive key on every request. Click the pill again to make the key active.

Use this control to stop an integration for a short time and keep the key.

Deleting a key

WARNING

Deletion is immediate and permanent. Any integration that uses the key receives an authentication error at once.

Click the bin icon on the row, then confirm.

Using the API

The base path is /api on your panel host. There is no version segment in the path.

Send the key in the Authorization header:

Authorization: Bearer bp_your_key_here

The same header carries either a session token or an API key. The panel treats a value that starts with bp_ as an API key.

Requests and responses use JSON.

Error responses

Message	Cause
Invalid API key	The key does not exist, or the value is wrong.
API key has expired	The key passed its expiration date.
API key has no scopes assigned	The key holds no permissions.
IP address not allowed	The request came from an address outside the IP restrictions.

Every accepted request updates the Last Used date of the key.

Route groups

These groups are open without a key:

Path	Purpose
/api/health	Health checks.
/api/version	The panel version.
/api/settings	The public settings, branding, theme, and feature flags.
/api/status	The public status page data.
/api/announcements/public	Public announcements.

These groups need a key or a session:

Path	Purpose
/api/auth	Authentication and the current identity.
/api/account	Profile, password, sessions, and personal tokens.
/api/servers	Server listing, power, files, backups, databases, and schedules.
/api/notifications	Notifications.
/api/support	Support tickets.
/api/billing	Orders, invoices, and credits.

These groups need an admin key:

Path	Purpose
/api/admin/users	Accounts.
/api/admin/roles and /api/admin/permissions	Roles and the permission catalogue.
/api/admin/api-keys	API keys.
/api/admin/sessions	Active sessions.
/api/admin/resellers	Resellers.
/api/admin/servers	Servers.
/api/admin/nodes and /api/admin/allocations	Nodes and allocations.
/api/admin/nests and /api/admin/eggs	Nests and eggs.
/api/admin/billing	Products, orders, invoices, and coupons.
/api/admin/webhooks	Webhooks.
/api/admin/settings	Panel settings.

The daemon paths (/api/daemon, /api/nodes, /api/remote, /api/internal, /api/orchestrators) use daemon credentials. An API key does not work on them.

An endpoint for a feature that your license does not include is not available.

Scopes

A key holds a set of scopes in the resource:action form:

Scope	Grants
servers:read	Read server details and status.
servers:write	Change server settings.
servers:power	Start, stop, and restart a server.
servers:console	Read and write the server console.
servers:files and servers:files.write	Read files, and create or edit files.
servers:database	Server databases.
servers:backup	Backups.
servers:schedules	Schedules.
servers:subusers	Subusers.
servers:settings and servers:startup	Server settings and startup values.
account:read and account:write	The account of the key owner.
billing:read and billing:write	Billing records.
admin:servers, admin:nodes, admin:users, admin:billing, admin:system	The matching admin areas.

A wildcard also works. servers:* grants every server scope. A single * grants everything.

Personal API tokens

A user can create a personal token from Account > API Tokens. That token acts as the user. Read Account Settings for the steps.

Good practice

• Give each integration its own key. Do not share one key between systems.
• Add IP restrictions. A restriction limits the damage from a leaked key.
• Grant the minimum permissions. A monitoring bot does not need server deletion.
• Rotate a key on a schedule. Create the new key, update the integration, then delete the old key.
• Read the Last Used column. A key with no recent use can be a forgotten key. Delete the keys that you do not need.

Next steps

• User Management - manage accounts.
• Roles and Permissions - understand the permission list.
• Panel Statistics - the API Docs tab holds curl examples.