API keys

The same key management you have under API & Developers in the app, as endpoints, so a deploy pipeline can rotate its own credentials. Every call is scoped to the workspace of the key that makes it: you can never see or change another workspace's keys, and a key you create here reaches only this workspace. See Authentication for permission levels and rotation rules.

A key's value is returned once, in the response that creates it. Every other response describes a key without its value: a hint with the prefix and last four characters is enough to tell keys apart.

The key object

{
  "id": "key_3f9c2a71b04d8e56",
  "name": "HubSpot sync",
  "hint": "brk_live_...9f2e",
  "mode": "live",
  "permission": "write",
  "status": "active",
  "created_at": "2026-09-27T10:02:11.000Z",
  "created_by": "dashboard",
  "last_used_at": "2026-09-27T14:40:00.000Z",
  "expires_at": null,
  "revoked_at": null,
  "rotated_from": null,
  "rotated_to": null
}

List keys

GET https://api.bluereacher.com/v1/keys

Requires read. Returns the workspace's active and rotating keys, newest first. The key making the call carries "current": true.

{ "data": [ { "id": "key_3f9c2a71b04d8e56", "name": "HubSpot sync", "current": true, "...": "..." } ], "managed": true }

The shared sandbox key belongs to no workspace, so it gets "data": [] and "managed": false.

Create a key

POST https://api.bluereacher.com/v1/keys

Requires admin. Body: name (up to 64 characters) and permission (read, write or admin, default write). Returns 201 with the key object plus key, the full value, shown this once. A workspace holds up to 25 active keys.

curl -X POST https://api.bluereacher.com/v1/keys \
  -H "Authorization: Bearer $BLUE_REACHER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Reporting job", "permission": "read" }'

Rotate a key

POST https://api.bluereacher.com/v1/keys/{key_id}/rotate

Requires admin. Body (optional): grace_hours, one of 0, 1, 24, 72, 168; default 24. Returns 201 with the replacement (same name and permission) including its key value, plus previous, the old key, now rotating with its expires_at. With grace_hours: 0 the old key is revoked at once.

Rename or change permission

PATCH https://api.bluereacher.com/v1/keys/{key_id}

Requires admin. Body: name, permission, or both.

Revoke a key

DELETE https://api.bluereacher.com/v1/keys/{key_id}

Requires admin. Permanent, and idempotent. Requests with the key fail with 401 invalid_api_key ("reason": "revoked") within a minute. The workspace's last active key cannot be revoked (409 last_key); create or rotate to a replacement first.

Errors