API keys

An API key is how something other than a person talks to this panel: your billing package creating an account, a script checking a backup overnight, an integration updating DNS. You mint them under Platform → API keys.

Everything on this screen comes down to three decisions you make once and that are fixed afterwards: which node group the key belongs to, which level it carries, and which scopes it gets. This article is about those three, and about what happens when you lose a key.

The group is the outer boundary

A key belongs to exactly one node group, and outside that group it can do nothing: not read, not change, not even see that something exists. If a request made with a group A key names a server, an account, a plan, a login or a migration in group B, it comes back 403 — before any node is contacted, and whether it was a read or a write. Listings are narrowed the same way: a key never sees another group's rows at all.

That binding cannot be changed later. Rotating keeps it; a key for another group is another key. The form says so before the key exists, which is the only moment saying it helps.

Level, and "acts as"

Besides its group a key carries a level — admin, server administrator, reseller or user. A key can never do more than that level may do under its own accounts. This is the same check the browser panel applies to a person, run server-side against the same code.

Below server administrator a key also belongs to one login: it reaches that login's accounts and nobody else's. Pick a reseller and the key reaches their customers; pick a user and it reaches only their own hosting.

Scopes: reading and changing are two things

A key carries scopes shaped family:action — accounts:manage or dns:read, for example. A GET needs :read, anything that changes state needs :manage. Note that :manage does not imply :read on the server. The screen therefore ticks reading along for you when you turn changing on; anybody minting a key from the command line has to grant both by hand.

The boxes you see come from the server: only families that actually have routes appear. A box that would grant nothing cannot exist, and a family added later shows up without this screen changing.

The secret is shown once

On create and on rotate the panel shows the secret exactly once. After that it keeps only a hash: it cannot show it again — not to you, not in the audit log. Lost it? Rotate the key. The group, the scopes and the audit trail stay; only the secret is new, and the old one stops working immediately, with no grace period.

The reveal card has a Show button and does not display the secret by itself, because a control panel is often on a shared screen.

Rate limit, revoking, and how you use it

Each key has its own bucket: a number of requests per minute plus a burst, both settable per key. Exceed it and you get a 429 with a Retry-After header in seconds. Ask for a higher limit rather than retrying into it.

Revoking is final and cannot be undone; revoked keys stay in the list (switch Show revoked keys on) so the trail stays readable.

# The key as a bearer token; the prefix is part of it
curl -sS -H "Authorization: Bearer corecp_<prefix>_<secret>" \
  https://panel.example.com/api/v1/accounts

# A change is a task. 200 = settled within the wait, 202 = still running
curl -sS -X POST -H "Authorization: Bearer corecp_<prefix>_<secret>" \
  -H "Content-Type: application/json" -d '{"domain":"example.com"}' \
  "https://panel.example.com/api/v1/accounts/myaccount/domains?wait=45s"

A failure always comes back as {"error": {"code": …, "message": …}}. Match on code and never on the sentence: the codes are stable, the sentences are not.

See also

• Integrations — the ready-made connections that bring their own key.
• Access to a server — what a person may do, and where the same levels come from.
• Checking the audit log — where a key's use is recorded.
• Platform settings — where node groups are managed.