Atomically rotate a child API key

const url = 'https://saperly.com/api/v1/keys/id/rotate';
const options = {
  method: 'POST',
  headers: {'Idempotency-Key': 'Idempotency-Key', Authorization: 'Bearer <token>'}
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "key": {
    "id": "string",
    "key_prefix": "sk_live_abc",
    "environment": "live",
    "name": "string",
    "agent_label": "string",
    "line_id": "string",
    "permissions": "full",
    "monthly_cap_cents": 1,
    "monthly_spend_cents": 1,
    "created_at": "2024-01-15T09:30:00Z",
    "revoked_at": "2024-01-15T09:30:00Z",
    "last_used_at": "2024-01-15T09:30:00Z",
    "rotated_from": "string",
    "created_by_service_key_id": "string",
    "plaintext_key": "sk_live_abc123def456..."
  }
}

Atomically revokes a child API key and mints a replacement that inherits its configuration (`name`, `agent_label`, `line_id`, `permissions`, `monthly_cap_cents`). The new key's `rotated_from` field references the OLD key's id. Old and new rotation happen inside one SQL transaction — partial rotations are impossible. The plaintext of the new key is returned in `plaintext_key` EXACTLY ONCE. Idempotency replays within 12 hours return the redacted row (no `plaintext_key`). Reusing the same `Idempotency-Key` for a rotation on a DIFFERENT child key returns 409 `idempotency_key_reused`. Rate-limited to 30 requests per hour per service key. 429 responses carry `Retry-After: 120`.

const url = 'https://saperly.com/api/v1/keys/id/rotate';
const options = {
  method: 'POST',
  headers: {'Idempotency-Key': 'Idempotency-Key', Authorization: 'Bearer <token>'}
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "key": {
    "id": "string",
    "key_prefix": "sk_live_abc",
    "environment": "live",
    "name": "string",
    "agent_label": "string",
    "line_id": "string",
    "permissions": "full",
    "monthly_cap_cents": 1,
    "monthly_spend_cents": 1,
    "created_at": "2024-01-15T09:30:00Z",
    "revoked_at": "2024-01-15T09:30:00Z",
    "last_used_at": "2024-01-15T09:30:00Z",
    "rotated_from": "string",
    "created_by_service_key_id": "string",
    "plaintext_key": "sk_live_abc123def456..."
  }
}

Atomically revokes a child API key and mints a replacement that inherits its configuration (name, agent_label, line_id, permissions, monthly_cap_cents). The new key’s rotated_from field references the OLD key’s id. Old and new rotation happen inside one SQL transaction — partial rotations are impossible.

The plaintext of the new key is returned in plaintext_key EXACTLY ONCE. Idempotency replays within 12 hours return the redacted row (no plaintext_key). Reusing the same Idempotency-Key for a rotation on a DIFFERENT child key returns 409 idempotency_key_reused.

Rate-limited to 30 requests per hour per service key. 429 responses carry Retry-After: 120.

Authentication

AuthorizationBearer

Service keys (sk_svc_*) authenticate the /v1/keys/* management plane. Send as Authorization: Bearer <service-key>. Service keys are minted only from the portal (Settings → Service Keys); there is no API path to mint another service key.

Path parameters

idstringRequiredformat: "uuid"

Child API key ID

Response

Child API key rotated

keyobject

Returned by POST /v1/keys and POST /v1/keys/{id}/rotate on the FIRST call only. Idempotency replays within the 12-hour TTL return the same row WITHOUT the plaintext_key field — the plaintext is never re-disclosable.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

Atomically rotate a child API key

Atomically rotate a child API key

Authentication

Path parameters

Headers

Response

Errors

Authentication

Path parameters

Headers

Response

Errors

1	const url = 'https://saperly.com/api/v1/keys/id/rotate';
2	const options = {
3	method: 'POST',
4	headers: {'Idempotency-Key': 'Idempotency-Key', Authorization: 'Bearer <token>'}
5	};
6
7	try {
8	const response = await fetch(url, options);
9	const data = await response.json();
10	console.log(data);
11	} catch (error) {
12	console.error(error);
13	}

1	{
2	"key": {
3	"id": "string",
4	"key_prefix": "sk_live_abc",
5	"environment": "live",
6	"name": "string",
7	"agent_label": "string",
8	"line_id": "string",
9	"permissions": "full",
10	"monthly_cap_cents": 1,
11	"monthly_spend_cents": 1,
12	"created_at": "2024-01-15T09:30:00Z",
13	"revoked_at": "2024-01-15T09:30:00Z",
14	"last_used_at": "2024-01-15T09:30:00Z",
15	"rotated_from": "string",
16	"created_by_service_key_id": "string",
17	"plaintext_key": "sk_live_abc123def456..."
18	}
19	}