---
title: "Rotate a key"
description: "POST /keys: Issues a new partner key and sets the key you called with to expire."
url: https://docs.tryflume.ai/api/rotate-key
updated: 2026-11-11
---

# Rotate a key

> POST /keys: Issues a new partner key and sets the key you called with to expire.

Issues a new partner key and sets the key you called with to expire.

```http
POST https://sandbox-api.tryflume.ai/partner/v1/keys
```

- `secret` is returned once.
- The key you called with keeps working for `overlap_days`.
- `Idempotency-Key` is required.

## Request

### Headers

| Header | Required | Description |
|---|---|---|
| `X-Flume-Partner-Key` | Yes | Your partner key. |
| `Idempotency-Key` | Yes | A new value for each rotation. |

### Body (`application/json`)

### Sample

**curl**

```sh
curl -X POST "https://sandbox-api.tryflume.ai/partner/v1/keys" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "rotation 2026-Q4",
  "overlap_days": 7
}'
```

**Python**

```python
import os
import uuid

import requests

headers = {
    "X-Flume-Partner-Key": os.environ["FLUME_PARTNER_KEY"],
    "Idempotency-Key": str(uuid.uuid4()),
}

response = requests.post(
    "https://sandbox-api.tryflume.ai/partner/v1/keys",
    headers=headers,
    json={
        "label": "rotation 2026-Q4",
        "overlap_days": 7,
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

**Node.js**

```js
import { randomUUID } from "node:crypto";

const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/keys", {
  method: "POST",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "label": "rotation 2026-Q4",
    "overlap_days": 7
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());
```

## Returns (201)

Every field is always present. A field with no value is `null`.

| Field | Type | Description |
|---|---|---|
| `key_id` | string | The key's id. Use it to revoke the key. |
| `prefix` | string | The start of the key. Safe to log. |
| `label` | string or null | The name you gave the key. |
| `status` | enum | `ACTIVE`, `EXPIRING` (replaced, and working until `expires_at`), `REVOKED` or `EXPIRED`. |
| `created_at` | string | When the key was issued, in UTC. |
| `last_used_at` | string or null | When the key was last used, in UTC. |
| `expires_at` | string or null | When a replaced key stops working, in UTC. |
| `secret` | string or null | The new key. Returned once. `null` when you replay an `Idempotency-Key`. |

**Response (201)**

```json
{
  "key_id": "pk_3f9a1c2e5b7d4a6f8e0c1b2d3a4f5e6d",
  "prefix": "sk_dev_acme_Qm4t",
  "label": "rotation 2026-Q4",
  "status": "ACTIVE",
  "created_at": "2026-10-16T08:00:00Z",
  "last_used_at": null,
  "expires_at": null,
  "secret": "sk_dev_acme_Qm4tW…"
}
```

## Errors

| Status | Code | Meaning |
|---|---|---|
| 401 | `EMBED_TOKEN_INVALID` | You sent an `Authorization` header and no `X-Flume-Partner-Key`. Flume read the call as one from its own iframe. |
| 401 | `PARTNER_KEY_INVALID` | The partner key is missing, unknown, revoked, expired, or from the other environment. On live, also a platform Flume has not enabled yet. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | The first call with this key is still running. |
| 409 | `KEY_LIMIT_REACHED` | You already hold the maximum number of active keys. |
| 422 | `IDEMPOTENCY_KEY_REUSED` | The key was already used with a different body. |
| 422 | `VALIDATION_FAILED` | A field is missing, unknown or has an unusable value. `field` names it as a dotted path. Some refusals carry the detail in `details` and leave `field` empty. |
| 429 | `KEY_ROTATION_RATE_LIMITED` | You reached the number of keys you can issue in 24 hours. Your current key keeps working. |
| 500 | `INTERNAL` | Something failed on Flume's side. |

Every code, with its fix: [API error codes](https://docs.tryflume.ai/api/errors.md).

Guide: [Rotate keys](https://docs.tryflume.ai/guides/rotate-keys.md).