Skip to Content

API Settings

The API Settings page manages your QuickBox Pro API connection and provides tools for local integrations. It is organized into four sections: API Status, Telemetry, Local API Keys, and the API Playground.

Admin only
Info

API Settings requires admin privileges (admin.system.api permission). Navigate to System > API Control from the sidebar.


Key features

API Status

View your connection status to QuickBox Central and activate or deactivate this server's API key

Telemetry Controls

Turn on the optional heartbeat to QuickBox, preview its data, and see what it sends

Local API Keys

Generate and manage API keys for local integrations and automation

API Playground

Test API endpoints interactively from within the dashboard


API status

The QuickBox Central banner at the top of the page shows the connection between your server and QuickBox Central. Its header shows the server’s Instance ID and the masked API key, plus an Activated or Not activated badge. These are display only. The instance ID is created when you activate the server, so you never type it in.

A server activates with an API key, a key that starts with qbp_. You copy it from API keys in your QuickBox account (see API keys). Your license key is the master key that lets your account hold API keys. It is never entered on a server.

Activate this server

  1. Open System > API Control.
  2. Expand the QuickBox Central banner with its Manage API key toggle.
  3. Paste the API key into the API key field (placeholder “Enter your API key”).
  4. Select Activate. The button stays disabled until the field has a key.

The field is masked, and the key is not shown again after you submit it.

Deactivate this server

When the server is activated, the expanded panel shows Deactivate instead of the key field. Select it and confirm Deactivate API key? to stop using this server’s activation. The server then stays deactivated until you activate an API key again.

A valid, activated API key is required for license validation, update checks, and accessing the QuickBox software catalog.

Changing to a different key from the CLI
Note

qb manage api -k qbp_YOUR_API_KEY releases this server’s current activation first, then activates the new key. If the new key is wrong, the server is left deactivated. In the dashboard, the key field appears only while the server shows Not activated, so deactivate first when you switch keys.


Telemetry

The Telemetry panel controls the heartbeat your server sends to QuickBox Central. Telemetry is off by default on new installs; it only runs after you turn it on. Servers installed before this default changed keep whatever setting they already had.

To turn it on or off, use the toggle in the Telemetry panel, or run:

bash
qb manage telemetry -o on
qb manage telemetry -o off
qb manage telemetry -o status

When telemetry is on, the server sends one heartbeat every 5 minutes by default. You can change the schedule from the panel, but a server is shown offline in your QuickBox account after 7 minutes without a heartbeat, so a longer interval makes it appear offline between check-ins. The data is tied to your license and server, so it is not anonymous. Each heartbeat contains:

  • Server identity — hostname, public and local IP address, operating system, and the QuickBox and dashboard versions
  • Licensing — your API key and server instance ID, which authenticate the request, plus the number of seats in use
  • Hardware and load — CPU model, core count, frequency and usage, load averages, uptime, and total, used, and free memory and disk
  • Network — interface name, current speeds, monthly received and sent totals, and your latest speed test result (download, upload, ping, jitter, test tool, and time)
  • User accounts — every account’s username, email address, active status, and last login, with that user’s pending application updates (application, installed version, and available version)
See exactly what is sent
Tip

Select Preview Payload in the Telemetry panel to view the data your server would send on the next heartbeat. Send Test sends one heartbeat immediately.

With telemetry off, your license, update checks, and every dashboard feature work normally. Your QuickBox account still lists the server, but it cannot show whether the server is online, because online status comes from the heartbeat. A server is marked offline after 7 minutes without one. For the full field list and how the account dashboard uses it, see Server Telemetry.


Local API keys

Local API keys let scripts and tools call the dashboard API without logging in. The panel holds two keys: a Read Key and a Write Key.

Managing keys

  • View Key - Show or hide a key stored in the dashboard, and copy it
  • Rotate - Make a new key. The old key stops working immediately
  • Clear - Remove the stored key

What each key can do

The keys act as the server’s main admin account, so they reach admin endpoints too, such as /api/admin/users.

KeyWhat it can do
Read KeyRead everything (GET requests). Any request that changes something is refused with 403.
Write KeyEverything: every endpoint and every method, including admin endpoints
Login onlyA key never works here: viewing, rotating or clearing the keys, sign-in, two-factor and passkeys, impersonating a user, and the web terminal

Using the keys

Send the key in the X-API-Key header. A key request needs no login and no x-csrf-token. This example creates a user with the Write Key:

bash
curl -H "X-API-Key: YOUR_WRITE_KEY" -H "Content-Type: application/json" \
  -d '{"username":"newuser","password":"CHOOSE_A_PASSWORD","email":"newuser@example.com"}' \
  https://your-server/api/admin/users

This example reads with the Read Key:

bash
curl -H "X-API-Key: YOUR_READ_KEY" https://your-server/api/system/status

Authorization: Bearer YOUR_KEY works too. In Postman, add a header named X-API-Key with your key as the value.

The older ?auth=YOUR_KEY URL parameter still works, but use it only for older tools. A key in the URL can end up in web server logs.

A wrong or missing key returns 401 on admin endpoints and 403 on the older key endpoints. A Read Key on a request that changes something returns 403.

Needs a dashboard update
Note

Keys on admin endpoints need a dashboard update that includes this support. Until your server has it, admin endpoints answer only to a logged-in admin session.

If you prefer a login session, log in with POST /api/auth/login and reuse the cookies. Change requests then also need the x-csrf-token header, set to the qb_csrf cookie value.

Key security
Warning

Treat API keys like passwords. The Write Key can do anything the server’s main admin account can. Store keys securely, do not share them in public channels, and rotate a key from System > API Control if it leaks.

Linked to QBxBot
Note

If you link your account to the QBxBot Command Channel, that link is bound to a Local API Key. Rotating or clearing the bound key disconnects the link automatically, and you will need to link again with the new key.


API playground

The API Playground lets you test API endpoints interactively from within the dashboard. Send requests to any available endpoint and view the response directly — useful for verifying integrations or exploring the API before writing automation scripts.

  • Select an endpoint and method
  • Provide request parameters or body content
  • Execute the request and inspect the response
  • Save frequently used requests for quick access

CLI equivalent

Dashboard ActionCLI Command
View API statusqb manage api -o status
Activate with an API keyqb manage api -k qbp_YOUR_API_KEY
Deactivateqb manage api -o deactivate
Send heartbeatqb manage api -o heartbeat
Check connectionqb manage api -o check

qb manage api -o deactivate asks for confirmation, then asks whether to activate again. Answer no to leave the server deactivated.

Dashboard advantage
Tip

The API Playground and local API key management are dashboard-exclusive features. The CLI provides basic API key activation and status checks, but the interactive playground is only available through the web interface.


Best practices

Do

  • Keep this server's API key valid — an invalid or revoked key prevents update checks and license validation
  • Use the Read Key for tools that only read data, and keep the Write Key for tools that must change things
  • Use the API Playground to test requests before building automation scripts — it is the fastest way to verify endpoint behavior
  • Rotate your keys now and then, and rotate at once if a key may have leaked

Don't

  • Don't share your API key or local API keys publicly — an API key identifies your server to QuickBox Central
  • Don't give the Write Key to a tool that only needs to read - it can change things
  • Don't expect your server to show as online in your QuickBox account while telemetry is off — online status comes from the heartbeat

FAQ


Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

  • Dedicated Support
  • Feature Previews
  • Community Configs
  • Active Discussions
Join Discord Server
Last updated on