# Rotate an API key's secret

`POST /o/{org}/api-keys/{key}/rotate`

A new secret for the same key; the old one stops working at once. The expiry is kept. Only the key's creator may rotate it; an expired key is `404`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org` | path | string | yes | The org's slug or id. A caller with no role in the org gets `404`. |
| `key` | path | string | yes | The key's `id` (`key_…`), not its secret. |

## Example request

```bash
curl -X POST "https://api.prix.dev/o/$RUSH_ORG/api-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $RUSH_TOKEN"
```

```typescript
const org = process.env.RUSH_ORG;
const keyId = process.env.KEY_ID;

const res = await fetch(`https://api.prix.dev/o/${org}/api-keys/${keyId}/rotate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RUSH_TOKEN}`,
  },
});

console.log(res.status, await res.json());
```

```python
import os

import requests

org = os.environ["RUSH_ORG"]
key_id = os.environ["KEY_ID"]

res = requests.post(
    f"https://api.prix.dev/o/{org}/api-keys/{key_id}/rotate",
    headers={"Authorization": f"Bearer {os.environ['RUSH_TOKEN']}"},
)

print(res.status_code, res.json())
```

## Responses

### 200

The key, with its new secret.

- `id` (string, required): `key_…`; use it in the key routes.
- `name` (string, required)
- `prefix` (string, required): The secret's first characters, to tell keys apart.
- `scopes` (array of string, required)
- `max_concurrent` (integer, required)
- `webhook_url` (string | null, required)
- `expires_at` (string | null, required)
- `created_by` (object, required)
  - `id` (string, required)
  - `email` (string | null, required)
- `last_used_at` (string | null, required)
- `created_at` (string, required)
- `secret` (string, required): The key's secret. Only in the create and rotate responses; never shown again.
- `webhook_secret` (string, optional): The webhook signing secret. Only in the update response that minted it.

### 401

No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.

### 404

No such resource for the caller, including one that exists in an org the caller cannot see.

## Example response (200)

```json
{
  "id": "key_Zq3T9vB1mN4pX8cR2wYe",
  "name": "ci-runner",
  "prefix": "rk_live_M3k8",
  "scopes": [
    "runs:read",
    "runs:write"
  ],
  "max_concurrent": 4,
  "webhook_url": null,
  "expires_at": "2027-01-01T00:00:00.000Z",
  "created_by": {
    "id": "5b8e2c1d-3f4a-4b6c-9d7e-8f9a0b1c2d3e",
    "email": null
  },
  "last_used_at": "2026-10-06T15:20:41.000Z",
  "created_at": "2026-10-06T15:00:00.000Z",
  "secret": "rk_live_M3k8…"
}
```