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

# Rotate API Key

> Generates a new API key and immediately invalidates the old one

## Overview

If your API key is compromised or you want to rotate it as a security practice, this endpoint generates a fresh key and immediately deactivates the old one.

<Warning>
  Update all your services **before** you rotate. The old key stops working the instant you call this endpoint — there is no grace period.
</Warning>

***

## Request

<ParamField header="X-Citadel-Key" type="string" required>
  Your **current** Aether Citadel API key (`ack_live_...`). This key will be invalidated.
</ParamField>

No request body required.

***

## Response

<ResponseField name="new_key" type="string">
  Your new API key. Update all environments that use the old key.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message reminding you to update your integration.
</ResponseField>

***

## Example

```bash theme={null}
curl -X POST https://api.aethercitadel.cloud/v1/tenant/rotate-key \
  -H "X-Citadel-Key: ack_live_YOUR_CURRENT_KEY"
```

```json theme={null}
{
  "new_key": "ack_live_d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8",
  "message": "Your old key is now invalid. Update your integration immediately."
}
```

***

## Rotation Checklist

After rotating your key, update it in:

* [ ] Server environment variables (`.env`, Kubernetes secrets, etc.)
* [ ] CI/CD pipeline secrets
* [ ] Any queued jobs or scheduled tasks that use the key
* [ ] Partner integrations that call Citadel on your behalf

***

## Error Responses

| Status | Error                          | Meaning                                      |
| ------ | ------------------------------ | -------------------------------------------- |
| `401`  | `Missing X-Citadel-Key header` | No key provided                              |
| `401`  | `Invalid or inactive API key`  | Key doesn't exist or was already deactivated |
| `503`  | `Multi-tenancy not configured` | Contact support                              |