Break glass

The Break glass screen lets you request an emergency access (extra roles or scopes for a limited time), follow it until two distinct people approve it, revoke it, and, as the beneficiary, issue the signed execution context that carries the elevation. Portal path: /security/break-glass, menu Security and governance > Break glass. It is used by any user of the tenant who needs an emergency access, and by security officers and tenant administrators who supervise and approve.

What the screen shows

The screen (BreakGlass in portal/src/screens/security-kit.tsx) starts with the hint "A grant needs two distinct approvers (security officer or tenant admin), never the requester or the beneficiary. Decide it in the approvals inbox.", then the Grants table read from GET /v1/break-glass (50 rows).

Column	Content
Grant	Identifier of the grant.
Requester	Who asked.
Beneficiary	Who receives the elevation (the requester by default).
Roles	Roles granted, for example tenant_admin.
Reason	Justification.
Status	pending, active, expired, rejected, revoked.
Approval	Identifier of the approval request.
Expires	End of the access.

Filter Status. A click on a row opens the grant loaded from GET /v1/break-glass/{grant_id}. An active grant past its expiry turns expired on the next read. Empty table: "No grant", "Request emergency access with a reason and a duration."

Form Request access:

Field	Default	Notes
Reason		Required, 10 characters at least.
Duration (s)	900	Required, from 60 to break_glass_max_seconds (3600 by default).
Roles		Comma separated tenant roles, for example tenant_admin; platform_admin is refused.
Scopes		Comma separated scopes. Roles or scopes: at least one.
Beneficiary		Default: you.
Incident reference		Link to the incident.

Actions

Button or action	What it does	API call	Roles
Request access (then Create)	Records the grant pending and opens an approval request with a quorum of two distinct approvers, the requester and the beneficiary excluded; audited as break_glass.request.	POST /v1/break-glass	Every user of the tenant
Revoke (row menu, grant pending or active)	Opens a form with an optional Reason, then Revoke: the elevation ends at once.	POST /v1/break-glass/{grant_id}/revoke	Requester; security_officer, tenant_admin for any
Issue context (row menu, grant active)	Opens a form with Audience (list) and Lifetime (seconds) (30 to 86400), then Issue context: returns a signed execution context carrying the elevation, bounded by the grant expiry, shown in a side panel.	POST /v1/break-glass/{grant_id}/context	The beneficiary only
Row click or View details	Opens the grant.	GET /v1/break-glass/{grant_id}	Requester, beneficiary; tenant_admin, security_officer, auditor
Filter, refresh icon	Applies the Status filter, reads the list again.	GET /v1/break-glass (query status)	Every user of the tenant

The approval itself is not decided on this screen: the two approvers decide it in the approvals inbox.

danger

A break glass grant raises privileges. Keep the Duration (s) short, fill Incident reference, and revoke the grant as soon as the emergency is over.

Roles

The portal hides no button on this screen; the row actions follow the status of the grant. The Control Plane (services/control-plane/src/eai/domains/delegation/routes.py and services/control-plane/src/eai/domains/delegation/break_glass.py) decides:

• any user of the tenant may request; tenant_admin, security_officer and auditor see every grant, other users only the grants they requested or receive;
• approvers are security_officer or tenant_admin, two distinct ones, never the requester nor the beneficiary;
• the requester, a security_officer or a tenant_admin may revoke;
• only the beneficiary may issue the execution context of an active grant;
• platform_admin passes every role check, but can never be granted through break glass.

Typical tasks

Get an emergency access

1. Request it. The access is bounded in time and tied to an incident. Click Request access, fill Reason (10 characters at least), Duration (s), Roles tenant_admin, Incident reference, then Create. Expected result: the message Created and a row pending with its Approval. If it fails: break_glass_duration_exceeded (HTTP 400) for a duration outside 60 to the maximum; invalid_request (HTTP 400) for an unknown role, platform_admin, no role nor scope, or a reason too short.
2. Have it approved. Two approvers decide the approval request in the approvals inbox. Ask two security_officer or tenant_admin, other than you and the beneficiary. Expected result: the status active and an Expires date. If it fails: the status rejected means an approver refused.
3. Issue the context. The elevation travels in a signed execution context. As the beneficiary, row menu > Issue context, optional Audience and Lifetime (seconds), then Issue context. Expected result: a side panel with the signed context. If it fails: forbidden (HTTP 403) when you are not the beneficiary; break_glass_not_active (HTTP 409) when the grant is not active; context_wrong_audience (HTTP 400) for an unknown audience.

End the access early

1. Revoke it. Revocation closes the elevation before its expiry. Row menu > Revoke, optional Reason, then Revoke. Expected result: the message Done and the status revoked. If it fails: break_glass_closed (HTTP 409) when the grant is already expired, rejected or revoked; forbidden when you are neither the requester nor an approver role.

Troubleshooting

Symptom	Cause	Fix
break_glass_duration_exceeded (HTTP 400)	The duration must be between 60 seconds and the maximum of the platform.	Lower Duration (s).
invalid_request (HTTP 400) with roles	A role is unknown or is platform_admin, or neither roles nor scopes were given.	Give tenant roles or scopes.
invalid_request with "a justification of 10 characters at least is required"	Reason is too short.	Write a longer justification.
validation_error (HTTP 422)	Duration (s) below 60 or Reason below 10 characters, refused before any check.	Fix the field.
break_glass_not_found (HTTP 404)	Unknown grant, or a grant you cannot see.	Check the identifier and your roles.
break_glass_not_active (HTTP 409)	The grant is not active.	Wait for the approvals, or request a new grant.
break_glass_closed (HTTP 409)	The grant is already closed.	Nothing to revoke.
context_wrong_audience (HTTP 400)	The audience is not known to the Context Authority.	Leave Audience empty or use a known audience.

Related pages

• Approvals
• Delegations
• Incidents
• Members and roles
• Identity, context, delegation
• Execution context guide