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

# Rotate API Key

> Rotate an existing API key, generating a new secret

## Overview

Rotates an existing API key by creating a **new key** with a **new ID** and the same name, scopes, rate limit tier, and metadata. The old key remains valid for a fixed 24-hour grace period to allow zero-downtime credential rotation in distributed systems. If the old key had a customer-set expiry sooner than 24 hours away, that earlier expiry is kept; rotation never extends a key's life.

The new key (including its new ID and secret) is returned only once in the response. Store it securely immediately.

Requires the `api-keys:manage` scope, and the caller must hold every scope of the key being rotated. This endpoint requires an `Idempotency-Key` header; see [Idempotency](/api-reference/introduction#idempotency). Retrying with the same key replays the cached response, including the **same** rotated secret, so an ambiguous network failure never rotates twice.

<Note>
  The grace period is fixed at 24 hours and is not configurable. The old key automatically stops working 24 hours after rotation, and a key in its grace period cannot be rotated again.
</Note>

## Path Parameters

<ParamField path="id" type="string" required>
  API key ID to rotate (e.g. `key_Mc2eF6gH`).
</ParamField>

## Response

Returns the **new** API key object, flat at the top level, with the same fields as [Create API Key](/api-reference/administration/create-api-key) including the one-time `key` secret. The `id`, `prefix`, `key`, and `created_at` all belong to the new key; the `name`, `scopes`, `rate_limit_tier`, and `metadata` are inherited from the rotated key.

<ResponseExample>
  ```json theme={null}
  {
    "id": "key_Qf6iJ0kL",
    "object": "api_key",
    "name": "Aurora Digital production",
    "key": "sig_b07dffe3ee95ea51d200ebb4f089a570c3e078a97d640ea6",
    "prefix": "sig_b07dffe3",
    "scopes": ["trademarks:read", "billing:read"],
    "rate_limit_tier": "standard",
    "status": "active",
    "expires_at": null,
    "last_used_at": null,
    "metadata": {},
    "revoked_at": null,
    "created_by": "key_Mc2eF6gH",
    "created_at": "2026-06-12T08:00:00.000Z",
    "updated_at": "2026-06-12T08:00:00.000Z",
    "request_id": "req_xQ3hI9jK"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.signa.so/v1/organization/api-keys/key_Mc2eF6gH/rotate" \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -H "Idempotency-Key: rotate-key-Mc2eF6gH-2026-06-12"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const rotated = await signa.organization.apiKeys.rotate("key_Mc2eF6gH");

  // Deploy rotated.key to your services within 24 hours
  console.log("New key:", rotated.key);
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                                                                                                    |
| ------ | ------------------ | -------------------------------------------------------------------------------------------------------------- |
| 400    | `validation_error` | Invalid key ID or missing `Idempotency-Key` header                                                             |
| 401    | `unauthorized`     | Missing or invalid API key                                                                                     |
| 403    | `forbidden`        | API key lacks `api-keys:manage`, the target is a system key, or the target has scopes the caller does not hold |
| 404    | `not_found`        | Key ID does not exist, is revoked, or is expired                                                               |
| 409    | `conflict`         | Key was already rotated and is still within its grace period                                                   |
| 429    | `rate_limited`     | Too many requests                                                                                              |

## Related Endpoints

* [List API Keys](/api-reference/administration/list-api-keys), view all keys
* [Create API Key](/api-reference/administration/create-api-key), generate a new key
* [Delete API Key](/api-reference/administration/delete-api-key), immediate revocation