# Rotate the API Secret

Replace your tenant's API secret. **The old secret stops working at once**: every request it signs is refused (`401` `Invalid signature`). For the Owner, Admin, Non-signing Admin and Security Admin roles.

## Overview

- The answer holds the new `apiSecret`. Store it in your server's configuration right away; you can read it again with [Get the API Secret](https://docs.aureahub.com/docs/admin-tenants-secret.md). The API key does not change.
- Rotate when someone who knew the secret leaves, when it may have leaked, and on your own schedule. To rotate without a gap, sign with a server credential instead: you hold two keys at once and revoke the old one when nothing uses it — [Credentials & Rotation](https://docs.aureahub.com/docs/guide-credentials.md).
- Your webhooks' signing secrets are separate: rotating the API secret does not change them.
- **Your tenant's quorum.** Where your tenant's quorum holds administrators' actions, this answers `202` `{ "state": "awaiting_quorum", "requestId" }` and nothing changes until another administrator approves it; you then read the new secret once with [Read the Answer](https://docs.aureahub.com/docs/quorum-request-result.md). See [Your Tenant's Quorum](https://docs.aureahub.com/docs/guide-tenant-quorum.md).
- The rotation is written to your tenant's [audit trail](https://docs.aureahub.com/docs/audit-events.md) [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md).

## Endpoint

### `POST /v1/admin/tenants/{id}/rotate-secret`

Authentication: bearer token required.

Replaces the tenant's API secret; the old one is refused at once.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Your tenant's id |

**Responses**

`200` OK

```json
{
  "apiSecret": "as_EXAMPLE000000000000000000000000000000000000000000000000000000002"
}
```

`202` Held for the Quorum

```json
{
  "state": "awaiting_quorum",
  "requestId": "4e2b9c17-8a3d-4f60-b5e1-7c9d0a2f6b38"
}
```

`403` Forbidden

```json
{
  "error": "ForbiddenError",
  "message": "Admin access required or you can only access your own tenant."
}
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/admin/tenants/TENANT_ID/rotate-secret \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

Web version: https://docs.aureahub.com/#admin-tenants-rotatesecret