API keys

An API key is the credential an executor presents to authenticate with Novacula. Every key starts with the exc_ prefix and is scoped to one organization — a key issued in org A cannot connect an executor under org B. Paste the key into your executor when you connect it — see Connect an executor for the flow, and the bare-metal or Kubernetes recipe for exactly where it goes. The same key type is created here and in the Connect an executor flow — there is no separate “personal” key. To manage keys, open API keys from the sidebar.

​

Create a key

1. On API keys, select New key.
2. Target — choose New executor to issue a key for an executor you haven’t connected yet, or pick an existing executor to bind the key to it. Targeting an existing executor rebinds it to the new key on its next successful sync (a targeted alternative to rotation), and pre-fills the name from that executor.
3. Name — 1–32 characters, shown in the key list. Pick something descriptive, like prod-cluster-1 or eu-bare-metal-3.
4. Expires in (days) — optional. Leave it empty to issue a key with no expiry.
5. Select Create.

The full key is shown once, on the confirmation dialog. If you targeted an existing executor, update it to use the new key — its next successful sync binds it to the new key. Select I’ve stored this key to dismiss the dialog. The name and expiry are fixed once created. Rotation keeps the same expiry — to get a key with a different expiry, create a new key.

​

View keys

The API keys list shows every key in your active organization: Use Last used to spot keys no executor is presenting anymore — good candidates to revoke.

​

Rotate

Rotation replaces a key with a fresh one and revokes the old key in a single step. Open the actions menu on a key and select Rotate. The new key is named after the old one with a date suffix added (for example, prod becomes prod 260601), and its secret is shown once in the same one-time dialog as create. The old key flips to Revoked; the new one appears as Active. Rotate when:

• A key may have been exposed (seen on a laptop, in a chat, or in logs).
• A key is approaching its expiry and you want a fresh secret. Rotation preserves the original key’s expiry, so to extend the lifetime, create a new key with the expiry you want.

After rotating, paste the new key into the executor’s configuration so it keeps connecting.

​

Revoke

Revoking takes a key offline. Open the actions menu and select Revoke. The next time an executor presents that key, it fails to authenticate. The key stays in the list with a Revoked badge so its history is preserved. Revoking cannot be undone — to bring an executor back, issue a new key and update its configuration. To take a specific executor offline by its bound key, use Revoke executor access on the executor’s page.

​

Delete

Deleting removes a key from the list permanently. Delete is available only on revoked keys — to delete an active key, revoke it first. This two-step path is a deliberate safeguard against removing a key still in use. Open the actions menu on a revoked key and select Delete.

​

Permissions

• Create, rotate, revoke, delete: organization owners and admins.
• View (including Last used): any organization member.

The full key is shown only at creation. No one — not even an owner — can read an existing key afterward; the only way to recover access is to rotate or create a new key.

​

Best practice

• Issue one key per executor so revoking one executor never disrupts another.
• Set an expiry for short-term or contractor-issued keys.
• Rotate any key that may have been exposed, even if you cannot prove it leaked.
• Revoke before delete when retiring an executor — it gives you a moment to confirm you are removing the right key.