Developer & API keys

The Developer page (/developer) is where you set up programmatic access to your fleet: scoped API keys for automation and CI/CD, webhook endpoints that push signed events to your systems, and a compact API reference with a ready-to-copy curl. Programmatic API access is a Max-plan feature.

Preview — not yet wired to a live backend

This page is currently a functional mock. The keys and webhooks you create here live only in your browser session (a module-local store) and reset on reload — they do not authenticate real requests or deliver real events yet. The control-plane endpoints that back it are not built. Treat everything below as the intended design; use it to plan an integration, not to run one in production. The Control plane API page tracks what is actually callable today.

Create an API key, step by step

1. In the API keys card, click Create key to open the create drawer.
2. Enter a Label — a human name so you can recognise and revoke the key later (e.g. CI/CD — GitHub Actions).
3. Pick the minimum Scopes the integration needs. Available scopes: read (read-only across all resources), write (create / update / delete), servers (manage servers + agent commands), sites (manage sites, deploys, SSL), and billing (read invoices + subscription).
4. Click Create key. The full key is shown once on the next screen — copy it into a secret manager immediately. After you close the dialog, MZPanel keeps only a masked preview (mz_live_••••XXXX).

The full key is shown once

There is no way to reveal a key again after the reveal dialog closes — that is by design. If you lose it, revoke the key and create a new one.

What else you can do

• Revoke a key — the trash action on any key row removes it. A revoked key immediately returns 401 Unauthorized to anything still using it; this cannot be undone.
• Add a webhook endpoint — Add endpoint opens a drawer where you enter an HTTPS URL and pick which events to subscribe to: server.online, server.offline, deploy.succeeded, deploy.failed, backup.completed, ssl.renewed, site.down. On save, a per-endpoint signing secret (whsec_…) is shown once.
• Send a test ping — the send action on a webhook row POSTs a sample event so you can confirm your receiver is reachable.
• View recent deliveries — opens a drawer listing each delivery with its HTTP status code and time, so you can see at a glance whether an endpoint is healthy or failing.
• Enable / disable an endpoint — pause deliveries without deleting the endpoint.
• Delete an endpoint — stops all future deliveries; the delivery history is discarded.
• Browse the API reference — the bottom card groups the core endpoints (Servers, Sites, Backups, Deploy) by method and path, and gives a copyable curl example that pre-fills your first key’s masked token.

How it works

The design is a thin control-plane feature, not something the agent runs:

• API keys authenticate calls to the REST API at https://api.mzpanel.com/v1 with an Authorization: Bearer <key> header, in place of the dashboard’s session cookie. Keys are scoped, so a key can be limited to exactly what an integration needs.
• Webhooks are the reverse direction: when a subscribed event fires anywhere in your fleet, the control plane POSTs a signed JSON body to your endpoint with an X-MZ-Signature header. You verify that signature using the per-endpoint secret to confirm the payload really came from MZPanel.
• Events originate from the same control-plane machinery the dashboard already reacts to — agent connect/disconnect heartbeats, deploy job results, backup completion, SSL issuance/renewal, and uptime checks.

In the current build none of this is persisted server-side: the page reads from and writes to an in-memory store in the browser, so keys, secrets, and deliveries are illustrative.

API & automation

mz runs on a single VPS, so it does not apply to this account-level page. Programmatic control of the whole fleet goes through the REST API instead — the same /v1 surface the dashboard uses, authenticated with an API key once this feature ships.

curl https://api.mzpanel.com/v1/servers \
  -H "Authorization: Bearer mz_live_••••XXXX" \
  -H "Accept: application/json"

See Control plane API for the auth model, the job-dispatch pattern, and the error shape. For driving an individual box from its shell, see The mz CLI.

Gotchas & troubleshooting

• This page is a preview. Keys and webhooks are mock-functional and browser-local; they don’t authenticate requests or deliver events yet, and they reset on reload. Don’t wire a production integration against a key created here.
• API access is Max-plan. Programmatic access via API keys is a Max-tier feature. Lower tiers use the dashboard (session cookie) only.
• Keys are shown once. Copy the full value at creation; there’s no re-reveal. Lost key → revoke and reissue.
• Webhooks must be HTTPS. The endpoint URL has to start with https://; the form rejects plain HTTP.
• A “failing” endpoint means non-2xx deliveries. If deliveries show 5xx codes, check that your receiver is reachable and returns 2xx quickly; use Send test ping to reproduce.
• Scope minimally. Grant only the scopes an integration needs (prefer read alone where possible) so a leaked key has the smallest blast radius.

Related

• Control plane API — the REST surface, auth, and error shape.
• The mz CLI — driving a single box from its shell.
• Git connections — another integration surface in the Advanced hub.