> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Emergency Bypass

> Suspend enforcement of a single retrieval rule for a bounded window — fully audited, auto-expiring.

## Overview

Emergency bypass lets an authorized operator temporarily suspend enforcement of **one retrieval rule** when a critical situation requires immediate access to context that rule is suppressing. Every bypass is bounded (15 minutes to 2 hours), requires a written reason, and is fully audited — activation, every decision made through the bypassed rule, and deactivation all land in the audit log with the reason code `EMERGENCY_BYPASS`.

Emergency bypass is a safety valve, not a workflow. It exists for scenarios where a rule would prevent an agent from accessing information needed to resolve an urgent incident.

***

## When to Use Emergency Bypass

* A production incident requires an agent to access documents a rule is suppressing, right now
* A security investigation needs an agent to review suppressed context for threat analysis
* A misconfigured rule is denying context that should be allowed, and you need relief while you fix it

<Warning>Emergency bypass should never be used as a routine workflow. If you find yourself bypassing frequently, the rule itself needs adjustment — frequent bypass usage is a signal that your policy configuration does not match your operational reality.</Warning>

***

## How It Works

<Steps>
  <Step title="Operator activates bypass on one rule">
    An operator with the `recall_rules:bypass` permission calls the bypass endpoint for a specific rule, with a mandatory reason (at least 10 characters) and a duration of exactly 15, 30, 60, or 120 minutes. Activating a rule that already has an active bypass returns `409 Conflict`.
  </Step>

  <Step title="That rule stops enforcing">
    While the bypass is active, any request that reaches the bypassed rule in the priority cascade returns `allow` with the reason code `EMERGENCY_BYPASS` and your reason string. Only that one rule is suspended — higher-priority rules evaluate first and keep enforcing normally throughout the window.
  </Step>

  <Step title="Everything is audited, fail-closed">
    Activation and deactivation are first-class audit operations, and the bypass **fails if its audit entry cannot be written** — you cannot bypass without leaving a record. Each decision allowed through the bypassed rule is logged with `reason_code: "EMERGENCY_BYPASS"` and the rule's ID.
  </Step>

  <Step title="Bypass expires or is deactivated">
    Expiry is checked at decision time — no background job is involved, so there is no window where a stuck process leaves a bypass open past its deadline. The operator can also deactivate early with a `DELETE`; deactivating a rule with no active bypass returns `409 Conflict`. Either way, the transition back to normal enforcement is immediate.
  </Step>
</Steps>

***

## Activating and Deactivating

Bypass is controlled per rule via the REST API. Both calls require an operator whose role grants the dedicated `recall_rules:bypass` permission — separate from rule editing, so you can restrict who may pull the emergency lever. Harness (agent) keys cannot call these endpoints.

```bash theme={null}
# Activate: reason ≥ 10 characters, duration_minutes ∈ {15, 30, 60, 120}
curl -X POST 'https://api.visiqlabs.com/recall/rules/<rule_id>/bypass' \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Incident #1234 — rule suppressing runbook docs needed for diagnosis",
    "duration_minutes": 30
  }'

# Deactivate early
curl -X DELETE 'https://api.visiqlabs.com/recall/rules/<rule_id>/bypass' \
  -H "Authorization: Bearer <token>"
```

Both calls return the updated rule, including its bypass state: `bypass_active`, `bypass_reason`, `bypass_activated_by`, `bypass_activated_at`, and `bypass_expires_at`.

While a bypass is active, the rule shows a **Bypass active** badge in the dashboard's retrieval rules view.

***

## Audit Trail

Three kinds of entries record a bypass, all in the retrieval audit log:

**Activation** — `operation: "emergency_bypass_activate"`, with metadata:

| Metadata Field     | Description                               |
| ------------------ | ----------------------------------------- |
| `action`           | `"activate"`                              |
| `duration_minutes` | The requested window (15, 30, 60, or 120) |
| `activated_by`     | The operator who activated the bypass     |
| `activated_at`     | ISO 8601 activation timestamp             |
| `expires_at`       | ISO 8601 auto-expiry timestamp            |
| `rule_name`        | The bypassed rule's name                  |

**Decisions during the window** — normal decision entries whose `decision` is `allow`, whose `reason_code` is `EMERGENCY_BYPASS`, whose `reason` is the operator's reason string, and whose `rule_id` is the bypassed rule. Requests decided by other (non-bypassed) rules during the window carry their normal reason codes.

**Deactivation** — `operation: "emergency_bypass_deactivate"`, with metadata recording `deactivated_by` plus the original bypass details (`original_reason`, `original_activated_by`, `original_activated_at`, `original_expires_at`, `rule_name`).

Example activation entry:

```json theme={null}
{
  "id": "audit-entry-uuid",
  "agent_id": "system",
  "operation": "emergency_bypass_activate",
  "resource_type": "recall_rule",
  "decision": "allow",
  "reason_code": "EMERGENCY_BYPASS",
  "reason": "Incident #1234 — rule suppressing runbook docs needed for diagnosis",
  "rule_id": "rule-uuid",
  "metadata": {
    "action": "activate",
    "duration_minutes": 30,
    "activated_by": "user-uuid",
    "activated_at": "2026-04-13T10:00:00Z",
    "expires_at": "2026-04-13T10:30:00Z",
    "rule_name": "Deny tier3 from confidential data"
  },
  "created_at": "2026-04-13T10:00:00Z"
}
```

Bypass decisions flow through the same audit pipeline as every other decision — record envelopes with asynchronous Ed25519-signed receipts when artifact signing is enabled for your organization. See [Receipts](/record/receipts).

***

## Querying Bypass Events

Use the audit log API for post-incident review:

```bash theme={null}
# Every decision allowed through a bypassed rule
curl 'https://api.visiqlabs.com/v1/recall/audit-log?reason_code=EMERGENCY_BYPASS&start_date=2026-04-13T00:00:00Z' \
  -H "Authorization: Bearer <token>"

# Who activated bypasses, when, and for how long
curl 'https://api.visiqlabs.com/v1/recall/audit-log?operation=emergency_bypass_activate' \
  -H "Authorization: Bearer <token>"

# Deactivations (manual early ends)
curl 'https://api.visiqlabs.com/v1/recall/audit-log?operation=emergency_bypass_deactivate' \
  -H "Authorization: Bearer <token>"
```

This supports:

* Post-incident reviews to understand exactly what data was accessed during the window
* Compliance reporting to demonstrate that every bypass is documented, justified, and time-bounded
* Trend analysis — repeated bypasses of the same rule mean the rule needs fixing

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Write a real reason" icon="comment">
    The API enforces a minimum length, but make the reason genuinely useful: reference an incident number, ticket, or specific operational justification. It becomes the `reason` on every decision allowed through the bypassed rule.
  </Card>

  <Card title="Bypass only the blocking rule" icon="crosshairs">
    Bypass is deliberately scoped to a single rule — identify which rule is actually denying the context and bypass that one. If the rule is simply wrong, fix the rule instead of repeatedly bypassing it.
  </Card>

  <Card title="Pick the shortest window" icon="clock">
    Choose the smallest duration that covers the need — 15 minutes is often enough. Deactivate manually the moment the incident no longer needs the access; don't wait for auto-expiry.
  </Card>

  <Card title="Review after incidents" icon="magnifying-glass">
    After every bypass, query both the activation events and the `EMERGENCY_BYPASS` decisions to see what was accessed. Use the review to decide whether the rule needs adjustment to prevent the next bypass.
  </Card>
</CardGroup>