Skip to main content

Break-Glass

Break-glass is a controlled, temporary exception for strict mode. When strict mode denies calls for a registered asset because no policy decides them, an approved grant lets that one asset through for a limited time. It needs a request and an approval by a different person, it expires on its own, and every step is audited.

It exists for the case where an asset must work now and the right policy is not ready yet. It does not weaken any policy.

Lifecycle​

A super_admin requests a grant for one registered asset with a reason and a duration. Someone else decides it.

A request waits 60 minutes for a decision. Approval makes the grant active from that moment for the requested duration. An active grant ends when it is revoked or when its time runs out, and a request that is rejected or not decided in time never becomes active.

Expiry is derived from time, so an expired grant stops working at once. A rejected, revoked or expired grant does nothing, and a revocation takes effect on the very next call.

Who approves​

A request must be decidable by someone other than the requester. The requester never approves or rejects their own request, and API keys never request, approve, reject or revoke.

The request is refused with 409 no_eligible_approver unless the organization has another active super_admin, or the asset has an owner who is an active member with the user role. This is checked once, when the request is made. If the approver becomes unavailable afterwards, the request waits for another approver or expires after 60 minutes.

So an organization with a single super_admin can still use break-glass for assets owned by another member. The owner decides only grants for the assets they own, and for any other grant the API answers 404. An asset with no owner needs a second super_admin.

What a grant allows​

A grant applies only in strict mode, to the calls that strict mode would otherwise deny for that asset because no policy decides them:

For a registered asset with an active grant the call is allowed with its original reason (no_matching_policy or no_policies_assigned) and is recorded, billed and reported exactly as the same allow is under permissive. There is no new response shape and no new reason code. A call for an unregistered key is never covered, because a grant needs a registered asset.

A grant never overrides:

  • a policy deny, or a policy that requires approval: a matching policy decides before the mode is consulted;
  • an active kill switch, for the organization or for the asset, which is checked first;
  • any other asset: each asset needs its own grant.

Under permissive and observe a grant changes nothing, because those modes already allow these calls. If the grant lookup fails, the strict deny stands.

Who can use it​

ActionEndpointAPI keysuper_adminbilling_adminuserauditor
List grantsGET /v1/enforcement/break-glasspolicies:readAllowAllowOwned assets onlyAllow
RequestPOST /v1/enforcement/break-glassRefusedAllow (user JWT)DenyDenyDeny
Approve or rejectPOST /v1/enforcement/break-glass/{id}/approve and /rejectRefusedAllow, never own requestDenyOwned assets only, never own requestDeny
RevokePOST /v1/enforcement/break-glass/{id}/revokeRefusedAllowDenyDenyDeny

Writes need a plan that includes policy features. Any super_admin can revoke an active grant, including the person who requested it. All endpoints answer Cache-Control: no-store.

In the Console, open Settings and find Break-glass in the enforcement card. It lists pending and active grants first, with a countdown to the end of the request window or of the grant, then recent history. A super_admin can request a grant for a registered asset (with a reason and a duration; presets are offered up to 4 hours) and can revoke an active one. Approve and reject appear for a super_admin or for the owner of the asset, and never for the person who requested it. Each decision asks you to confirm. A user sees only the grants for the assets they own. If nobody else could decide a request, the Console explains that it needs another active super_admin or an active owner with the user role.

Using it​

POST /v1/enforcement/break-glass takes {"asset_id": "...", "reason": "...", "duration_minutes": 30} and returns 201 with the pending grant. POST .../{id}/approve returns 200. POST .../{id}/reject and POST .../{id}/revoke take an optional {"note": "..."} and return 200.

GET /v1/enforcement/break-glass returns break-glass.v1: pending and active grants first (newest request first), then up to 50 most recent others, with limit_active (5) and limit_pending (10). Each grant has id, asset_id, reason, duration_minutes, status (pending, approved, rejected, revoked or expired), requested_by, requested_at and pending_expires_at, and when they apply decided_by, decided_at, decision_note, expires_at, revoked_by and revoked_at.

  • Reason and note. The reason is required, 1 to 200 characters after trimming, no control characters. The optional note is at most 200 characters. Both are stored and audited in clear text and visible to every role that can read the list. Do not put personal data or secrets in them.
  • Duration. 1 to 240 minutes. The grant is active from approval, not from the request.
  • Errors. 400 invalid_asset, invalid_reason, invalid_duration, invalid_note; 403 self_approval_forbidden; 404 for an unknown asset or grant, or one that belongs to another organization (and, for an owner, a grant of an asset they do not own); 409 no_eligible_approver, grant_not_pending (already decided or expired), grant_not_active (revoking a grant that is not active), break_glass_active_limit_reached and break_glass_pending_limit_reached.

Audit​

EventWhenFields
breakglass.requestedA grant is requestedOrganization, grant ID, asset ID, actor, requester, duration, reason
breakglass.approvedA request is approvedOrganization, grant ID, asset ID, actor, requester, duration, expiry time
breakglass.rejectedA request is rejectedOrganization, grant ID, asset ID, actor, requester, note when given
breakglass.revokedA grant is revokedOrganization, grant ID, asset ID, actor, requester, note when given
breakglass.invokedA grant turned a strict deny into an allowOrganization, grant ID, asset ID, original reason, decision ID, operation ID when valid, transport, time
breakglass.expiredA grant or request reached its end without being revoked or rejectedOrganization, grant ID, asset ID, previous status (approved or pending), time it ended

The first four events are written in the same transaction as the change. The last two are written by a background worker: breakglass.invoked shortly after the allow, best effort, and breakglass.expired by a sweep that runs about every 60 seconds (operators of a self-hosted deployment can change the interval, see Limits and Configuration). If recording fails the allow is unchanged, so an invoked event can be missing, and the expiry event can appear after the grant already stopped working. Each is written once per grant. The invoked and expired events carry no free text and never the grant reason. None of these events is exported to write-once storage or sent as a notification or webhook; the allowed call itself is an ordinary decision.evaluated event, which is exported.

Limits​

  • At most 5 active grants and 10 pending requests per organization. The pending limit is checked when a request is made and the active limit when one is approved. Expired, rejected and revoked grants do not count.
  • A pending request is valid for 60 minutes.
  • A grant lasts at most 240 minutes (4 hours).
  • A grant covers one registered asset.

See also Enforcement Modes, Kill Switch, Audit and Access & Permissions.