Create and revoke an API key

An API key lets a script call the panel’s /api/v1 API without a person signing in. The script sends the key as Authorization: Bearer hyp_…. A key can never do more than the account that created it.

Before you start

• Sign in with a role that holds Manage API keys (remote management API). Owners and Administrators do. API keys is under Administration in the sidebar.
• Use an account whose scope is All hostings. Owners and Administrators qualify. An account with Only assigned scope is refused with “API keys require an account with cluster-wide scope. Per-tenant keys arrive in a later release.”
• Decide which capabilities the script needs. The list is the same as in the role builder. See Built-in roles and capabilities.

Steps

Create a key

1. Open API keys in the sidebar.
2. Under Create a key, type a Label that says what uses the key, such as ci-deploy. It is required and holds up to 120 characters.
3. Optionally set Expires, a date. The key stops working at the end of that day, UTC. Leave it empty for no expiry.
4. Optionally fill Allowed addresses with IPs or CIDR ranges, separated by commas, for example 203.0.113.0/24, 198.51.100.7. Empty allows any address.
5. Optionally set Requests per minute. 0 means unlimited.
6. Under What the key may do, tick the capabilities. A key gets only the capabilities you tick that your own account also holds.
7. Click Create key.

The page shows Copy this key now — it is not shown again with the full key. Copy it into your secret store before you leave the page. Only a short prefix is kept for display.

Revoke a key

Before you revoke a key

Every script using the key stops working immediately. Check the Last used column to see whether the key is still in use, and replace the key in your scripts first. A revoked key stays in the list greyed out with a revoked badge. This cannot be undone. Create a new key instead.

1. In the Keys table, click Revoke on the key’s row.
2. Confirm Revoke in the dialog. The page shows “API key revoked”.

When a user is deleted

Keys belong to the account that created them. Deleting that account deletes its keys, and scripts using them stop working. See Add and manage panel users. Revoke and recreate under a long-lived account if a script must outlive a person.

Check that it worked

• The Keys table shows the Prefix, Label, Capabilities (N caps, all caps or no caps), Restrictions (such as 1 IP · 60/min), Last used and Expires.

• Call the API with the key from an allowed address:

  read -rs API_KEY
  printf 'header = "Authorization: Bearer %s"\n' "$API_KEY" | curl -K - https://panel.example.com/api/v1/nodes

  The key goes to curl on standard input, because command-line arguments can be read by other local users through /proc. For the same reason, with hctl remote, export the key as HYPERION_API_KEY instead of using --key.

  The page links API docs and OpenAPI at the top for every endpoint.

• After a revoke, the same call is refused.

If it fails

• “API key label is required”: fill Label.
• “Invalid expiry date (use YYYY-MM-DD)”: use the date picker format.
• “Invalid IP/CIDR in the allowlist (use e.g. 203.0.113.0/24).”: fix Allowed addresses.
• “Rate limit must be a non-negative number (0 = unlimited).”: fix Requests per minute.
• “API key management requires permission”: your role lacks Manage API keys (remote management API).
• A key shows no caps: you ticked nothing, or your own account holds none of what you ticked. Create it again.