> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novacula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Create, view, rotate, and revoke the keys executors use to connect to Novacula

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](/docs/executors/connect-an-executor) for the flow, and the [bare-metal](/recipes/provision-on-bare-metal) or [Kubernetes](/recipes/provision-on-kubernetes) recipe for exactly where it goes.

The same key type is created here and in the [Connect an executor](/docs/executors/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](#rotate)), 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.

<Warning>
  Copy the key immediately and store it somewhere you can retrieve it during install — a password manager, a secrets vault, or your provisioning system. There is no way to see it again. If you lose it, [rotate](#rotate) the key to get a new one.
</Warning>

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:

| Column        | What it shows                                                                           |
| ------------- | --------------------------------------------------------------------------------------- |
| **Name**      | The label you gave the key, with its key ID underneath                                  |
| **Status**    | **Active**, **Expired**, or **Revoked**                                                 |
| **Used by**   | The executors connecting with this key                                                  |
| **Created**   | When the key was issued                                                                 |
| **Last used** | When an executor last presented the key, relative (`never` if it has not been used yet) |

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 — see [Update an executor's API key](/recipes/update-executor-key) for the exact steps on each backend, including recovering an executor that was offline during the rotation.

## 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](/docs/executors/deactivate-executor) 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.