Rotate keys

POST /keys issues a new partner key. The key you called with keeps working for overlap_days, so you can deploy the new key before the old one stops.

Before you begin

A working partner key. Flume issues your first one. See Authentication and keys.

1. List your keys

curl -X GET "https://sandbox-api.tryflume.ai/partner/v1/keys" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY"

import os

import requests

headers = {
    "X-Flume-Partner-Key": os.environ["FLUME_PARTNER_KEY"],
}

response = requests.get(
    "https://sandbox-api.tryflume.ai/partner/v1/keys",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/keys", {
  method: "GET",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

{
  "keys": [
    {
      "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": "2026-10-16T09:14:22Z",
      "expires_at": null
    },
    {
      "key_id": "pk_9e1b4d7a2c5f4068b3a1d9c7e5f2a0b4",
      "prefix": "sk_dev_acme_8f3k",
      "label": null,
      "status": "EXPIRING",
      "created_at": "2026-07-02T10:30:00Z",
      "last_used_at": "2026-10-16T07:58:41Z",
      "expires_at": "2026-10-23T08:00:00Z"
    }
  ]
}

`status`	Meaning
`ACTIVE`	Working
`EXPIRING`	Replaced by a newer key. Works until `expires_at`
`REVOKED`	Stopped by you
`EXPIRED`	Its overlap ran out

The list never contains a secret.

2. Issue the new key

Idempotency-Key is required.

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
}'

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

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

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

secret is the new key. It is shown once.
The key you called with becomes EXPIRING. It stops after overlap_days.
overlap_days is 0 to 30. The default is 7.
A replay of the same Idempotency-Key returns secret: null.

3. Deploy and revoke

Store the new secret in your secret manager.
Deploy it everywhere.
Check last_used_at on the old key with GET /keys.
Revoke the old key, or let its overlap run out.

curl -X DELETE "https://sandbox-api.tryflume.ai/partner/v1/keys/pk_9e1b4d7a2c5f4068b3a1d9c7e5f2a0b4" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY"

import os

import requests

headers = {
    "X-Flume-Partner-Key": os.environ["FLUME_PARTNER_KEY"],
}

response = requests.delete(
    "https://sandbox-api.tryflume.ai/partner/v1/keys/pk_9e1b4d7a2c5f4068b3a1d9c7e5f2a0b4",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.status_code)

const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/keys/pk_9e1b4d7a2c5f4068b3a1d9c7e5f2a0b4", {
  method: "DELETE",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(response.status);

Response: 204. No body.

A revoke takes effect at once. You cannot revoke your only working key.

Limits

	Sandbox	Live
Active keys	5	2
Keys issued in 24 hours	10	1

If a key leaks

The leaked key is	Do this
Not the one you call with	Call `DELETE /keys/{key_id}` on it. It stops at once
The one you call with	Call `POST /keys` with `overlap_days: 0`. The old key stops at once. Deploy the new secret

Then tell Flume. Send the key prefix, never the key.

Handle the errors

You get	Do this
`409` `KEY_LIMIT_REACHED`	Revoke a key you no longer use, then rotate
`429` `KEY_ROTATION_RATE_LIMITED`	Wait. Your current key keeps working
`409` `LAST_ACTIVE_KEY`	Issue a replacement before you revoke
`400` `IDEMPOTENCY_KEY_REQUIRED` on `POST /keys`	Send the `Idempotency-Key` header
`422` `VALIDATION_FAILED` on `POST /keys`	Fix the field named in `error.field`, for example `overlap_days`
`404` `NOT_FOUND`	Check `key_id`