Kill Switch
The kill switch is an emergency stop. While a switch is active, every call in its scope is denied with the reason kill_switch_active, whatever the policies, the enforcement mode or any break-glass grant say. Use it when you need to stop an asset, or all governed traffic, immediately.
A switch has one of two scopes:
| Scope | Covers |
|---|---|
organization | Every call for the organization, including calls for an asset key that is not registered. |
asset | Every call for one registered asset. It never applies to an unregistered key. |
How a call is checked
The check runs once per call, after the asset has been found, your access to it confirmed and the request metadata validated, and before any approval retry, policy or mode is looked at.
A call that fails the earlier checks is still refused as it always was (for example 400 for invalid input, 404 for an unknown asset id). After those checks, an active switch denies the call, an unreadable switch denies it with a 503, and otherwise the call continues as usual.
- Nothing is cached. Activating or deactivating a switch takes effect on the next call.
- Mode does not matter. A kill switch denies in
permissive,observeandstrict, and no mode lookup or break-glass lookup happens for a call it denies. - Not the playground. The Console playground does not run real decisions and ignores kill switches.
What the caller sees
The response is the same shape as a policy deny on /v1/evaluate and /v1/proxy/evaluate: HTTP 403, decision deny, reason kill_switch_active, with no policy ID and no approval fields. A deny for a registered asset carries a decisionId; a deny for an unregistered key does not.
The SDKs, the MCP adapter and the Envoy adapter treat it as an ordinary deny. The upstream or tool is never called, and it is never reported as a policy-engine outage. The MCP adapter and the Envoy MCP path show the reason in the tool result. The Envoy adapter for plain HTTP and gRPC includes reason in its deny body for kill_switch_active (exact match only) and never includes a decision ID.
What is recorded and billed
| Call | Recorded as a decision | Counted toward your decision quota |
|---|---|---|
| Registered asset, asset or organization switch | Yes, as decision.evaluated with result deny and reason kill_switch_active | Yes, like any recorded deny |
| Unregistered asset key, organization switch | No | No |
For an unregistered key there is no decision to record, so an enforcement.denied event is written instead, with reason kill_switch_active, mode killswitch, and only a sha256: digest of the asset key. The key is still queued for asset discovery. That event is written by a background worker shortly afterwards and is best effort, and the call is denied either way. A kill switch deny never records an operation allow and never creates an approval.
Approvals
The check runs before the approval retry, so while a switch is active an approved but unredeemed approval cannot be redeemed: the retry is denied with kill_switch_active and the approval stays approved. After the switch is deactivated the same approval can still be redeemed, but only within its normal expiry; the time passes while the switch is on. Pending approvals can still be approved or rejected during a switch. See Approvals & Webhooks.
If the switch cannot be read
If the kill switch state cannot be read while a call is handled, the call is denied: the API answers 503 with {"code": "enforcement_unavailable"}. Nothing is recorded or billed, and your upstream is never called. The SDKs and adapters treat it as an unavailable decision point and deny, never as an allow. This is the opposite of the mode setting, which falls back to permissive when it cannot be read: a control that can only stop traffic fails closed.
Who can use it
| Action | Endpoint | API key | super_admin | billing_admin | user | auditor |
|---|---|---|---|---|---|---|
| List switches | GET /v1/enforcement/kill-switches | policies:read | Allow | Allow | Allow | Allow |
| Activate | POST /v1/enforcement/kill-switches | Refused | Allow (user JWT) | Deny | Deny | Deny |
| Deactivate | DELETE /v1/enforcement/kill-switches/{id} | Refused | Allow (user JWT) | Deny | Deny | Deny |
Only a signed-in super_admin can activate or deactivate a switch, and API keys never can. Writing needs a plan that includes policy features; reading needs policy features or the playground. All three endpoints answer Cache-Control: no-store.
In the Console, open Settings and find Kill switch in the enforcement card. It lists active switches first, then recently deactivated ones. A super_admin can activate a switch for the whole organization or for one asset, and deactivate one. Activating asks you to confirm and states that every call in scope is denied immediately; deactivating also asks you to confirm. Other roles see the list and a note that only a super admin can change it.
Using it
POST /v1/enforcement/kill-switches takes {"scope": "organization" | "asset", "asset_id": "...", "reason": "..."} and returns 201 with the switch. asset_id is required for the asset scope and refused for organization. GET returns kill-switches.v1: active switches first (newest first), then up to 50 most recently deactivated ones. Each item has id, scope, asset_id (asset scope), reason, activated_by, activated_at, and when it has been deactivated deactivated_by and deactivated_at. DELETE returns 204.
- Reason. Required, 1 to 200 characters after trimming, no control characters (newlines and tabs included). It is stored and audited in clear text and shown to every role that can read the list. Do not put personal data or secrets in it.
- Errors.
400invalid_scope,invalid_asset(an asset scope withoutasset_id, or an organization scope with one) andinvalid_reason;404for an unknown asset or switch, or one that belongs to another organization, or a switch that is already inactive;409kill_switch_already_activeand409kill_switch_limit_reached. - Deleting an asset. Deleting an asset does not deactivate its switch. Deactivate it explicitly; an active switch for a deleted asset still counts toward the limit.
Audit
| Event | When | Fields |
|---|---|---|
killswitch.activated | A switch is activated | Organization, actor, scope, asset ID (asset scope), reason, switch ID |
killswitch.deactivated | A switch is deactivated | Organization, actor, scope, asset ID (asset scope), switch ID |
Each event is written in the same transaction as the change, and deactivated switches stay in the history. Denied calls appear as decision.evaluated (registered assets) or enforcement.denied (unregistered keys), as described above. These configuration events are not part of the export to write-once storage; the decision.evaluated events are.
Limits
- One active organization switch, and one active switch per asset.
- At most 100 active per-asset switches per organization. The organization switch is not counted.
- Reason: 1 to 200 characters.
- The list shows active switches and the 50 most recently deactivated ones.
See also Enforcement Modes, Break-Glass, Reason Codes and the Security Model.