Rotate a key

POSThttps://sandbox-api.tryflume.ai/partner/v1/keysCopy

RequestReturnsErrors

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

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

Guide: Rotate keys

curl

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

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

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());

Response: 201

{
  "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…"
}

Request

Headers

Header	Required	Description
X-Flume-Partner-Key	Yes	Your partner key. See Authentication and keys.
Idempotency-Key	Yes	A new value for each rotation.

Body

Send application/json. A field the API does not list returns a 422 that names it. The body is optional.

Returns

201 with these fields. Every field is always present. A field with no value is null.

• key_idstring

  The key's id. Use it to revoke the key.

• prefixstring

  The start of the key. Safe to log.

• labelstring or null

  The name you gave the key.

• statusenum

  ACTIVE, EXPIRING (replaced, and working until expires_at), REVOKED or EXPIRED.

• created_atstring

  When the key was issued, in UTC.

• last_used_atstring or null

  When the key was last used, in UTC.

• expires_atstring or null

  When a replaced key stops working, in UTC.

• secretstring or null

  The new key. Returned once. null when you replay an Idempotency-Key.

Errors

Every error uses one envelope. Branch on error.code.

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.