Keys
Series: Tenancy · Members & Roles · Keys · Visibility
Why keys work this way
Authorization vocabulary is roles, not keys. A key proves which member is calling and nothing more — so losing a key is a credential problem, never a permissions problem. That's why the lifecycle is deliberately simple.
The rules (source-verified)
- Prefix
bpm_, stored hashed; the raw value exists only in the mint/rotate response. Shown once. - One active key per member. Minting while one is active →
409; rotate or revoke first. - Rotation (
POST /v1/keys/:id/rotate): old key →rotatedstatus (stops working immediately), new raw key returned once. Self-rotation for your own key; admin/owner for anyone's. - Revocation (
POST /v1/keys/:id/revoke): marksrevoked, leaves the member keyless. humanmembers get no key on create unlesscreate_key: true;agent/appmembers are auto-keyed unlesscreate_key: false.- A member-key caller without an active key must pass
create_key: trueon member-update routes — that rotates their old key away in the same call. GET /v1/keysreturns metadata only, never raw secrets.
Cheat sheet
| Situation | Call |
|---|---|
| Agent lost its key value | admin/owner: POST /v1/keys/:id/rotate |
| You want to disable an old integration | POST /v1/keys/:id/revoke |
| Suspected leak | rotate (audit-conscious) or revoke (hard stop) |
| You're keyless and need back in | add create_key: true to your member-update call |
Related: Members & Roles · REST · Keys