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

# Rotate an Orbit Search API key with zero downtime

> Replace an active Orbit Search API key without dropping requests — issue a replacement key, migrate traffic gradually, verify usage, then revoke the old key.

Rotating an API key without downtime requires a careful sequence: issue the replacement first, migrate traffic gradually, confirm the new key is receiving requests, and only then revoke the old one. This guide walks you through each step so you can complete a rotation without dropping a single request.

<Warning>
  The raw API key is shown **only once** in the dashboard. As soon as it appears, store it in your secrets manager or environment configuration. You cannot retrieve the raw key again after this point; only non-secret metadata such as `display_key` and `last_used_at` remains visible.
</Warning>

## Steps

<Steps>
  <Step title="Issue a new key">
    Create the replacement key in the [Orbit developer dashboard](https://developer.orbitsearch.com/dashboard/keys) before touching anything in production. Give it a name that makes its purpose and environment clear, such as `"production search v2"`.

    ```bash theme={"dark"}
    export ORBIT_API_KEY_NEXT="sk_orb_NEW_KEY_VALUE"
    ```

    Store the raw key immediately. Keep the dashboard open long enough to copy the key's `display_key` or name for tracking during the rollout.

    <Tip>
      Use the `name` field to encode the key's purpose and environment — for example, `"production search v2"` or `"staging worker 2026-05"`. The `display_key` field (e.g., `sk_orb_a0186...55fd`) combines a non-secret prefix and suffix that you can safely show in dashboards, logs, and support tickets to identify a key without exposing the raw secret.
    </Tip>
  </Step>

  <Step title="Update one caller or environment">
    Pick one service, worker, or environment and update it to use the new key. Keep all other callers on the old key for now. This limits blast radius if something goes wrong with the new key.

    Update the relevant environment variable or secret:

    ```bash theme={"dark"}
    # Example: update a single environment's secret
    export ORBIT_API_KEY="sk_orb_NEW_KEY_VALUE"
    ```

    Deploy or restart only that one caller, then send a test request to confirm it returns a successful response.
  </Step>

  <Step title="Verify traffic on the new key">
    Open the dashboard key list or usage view and confirm the new key's `last_used_at` timestamp has advanced. This proves the key is being used in production.

    Example list response entry for the new key:

    ```json theme={"dark"}
    {
      "id": "new-key-uuid",
      "prefix": "sk_orb_b1297",
      "suffix": "66ge",
      "display_key": "sk_orb_b1297...66ge",
      "name": "production search v2",
      "scopes": ["search:read", "profile:read"],
      "created_at": "2026-05-05T10:00:00.000Z",
      "last_used_at": "2026-05-05T10:15:34.000Z",
      "expires_at": "2027-12-31T23:59:59.000Z",
      "is_active": true,
      "is_expired": false
    }
    ```

    If `last_used_at` is still null or unchanged, the caller has not switched over yet. Investigate before proceeding.
  </Step>

  <Step title="Move all remaining callers">
    Once you've confirmed the new key works, update every remaining service, worker, CI environment, and integration to use the new key. Redeploy or restart each caller as needed.

    Take your time here — both the old and new keys are active simultaneously, so there is no rush and no downtime risk during this phase.
  </Step>

  <Step title="Revoke the old key">
    Once all callers have moved to the new key and you've verified no traffic is hitting the old key, revoke it.

    Use **Dashboard** → **API keys** to revoke the old key.

    Revoked keys are immediately rejected by authentication and show `is_active: false` in list responses. They remain visible in the list as inactive metadata, which preserves an audit trail linking the key to past requests.

    <Info>
      Prefer revoke over delete for rotation. Deletion removes the key record entirely, which eliminates its audit trail. Revocation keeps the key visible in an inactive state so you (and support) can correlate historical request IDs and ledger entries back to the key that made them.
    </Info>
  </Step>
</Steps>

## What gets logged

Every key creation, revocation, deletion, expiry event, and failed authentication attempt is written to the audit log with non-secret key identifiers only (`id`, `display_key`). The raw key is never stored or logged after creation.