Emergency Controls

Tenant containment actions — halt/resume a tenant or environment, pause a connector, revoke a credential — with exact action names, required permission, side effects, and the event ledger.

advanced6 min readimplemented

Emergency Controls#

Emergency controls are the break-glass actions for containing an incident inside a tenant. They are exposed through the enterprise admin surface, restricted to the highest-privilege roles, and every invocation — success or failure — is recorded in a dedicated event ledger.

A request passes credential resolution, tenant match, and an enterprise permission check before reaching the emergency-control handler; each stage can fail closed with a specific HTTP status. — The fail-closed gate

Authorization#

Every emergency action requires the enterprise permission emergency:invoke, held only by owner and admin. Reading the emergency event log requires trust:read (every role). As with all admin routes, the credential's tenant, x-tenant-id, and the body tenantId must agree, or the call is rejected with 403 TENANT_MISMATCH.

These actions take effect immediately and tenant-wide

A tenant_halt puts the tenant into maintenance; an environment_halt flips a whole environment to halted; a token_revoke invalidates a live credential. Confirm the tenant and target before you invoke, and always pass a meaningful reason (it is required and is written to the audit ledger).

There is no CLI for this#

No `intended emergency …` command exists

The Intended CLI is a flat set of hyphenated commands and has no emergency-control command group. Emergency actions are invoked over the admin API (POST /admin/emergency-controls/:action) shown below, or from the account console. Do not script against an intended emergency … command — it does not exist.

Read current emergency state#

GET/admin/emergency-controlsRequires auth

Returns the tenant's recent emergency control events (most recent first). Requires trust:read.

tenantIdstring*Tenant identifier.

Invoke an emergency action#

POST/admin/emergency-controls/:actionRequires auth

Performs a containment action and returns the updated event list with the new event at the head. Requires emergency:invoke. The handler is fail-closed: if the underlying mutation fails, the event is still recorded with status: failed and an error in its metadata.

actionstring*Path parameter — one of the seven actions below.

tenantIdstring*Body field; must match credential and x-tenant-id.

reasonstring*Required incident rationale, recorded on the event.

environmentKeystringRequired for environment_halt / environment_resume.

targetRefstringRequired for connector_pause/resume (connector or connector:capability) and token_revoke (credential id).

metadataobjectOptional extra context merged into the event metadata.

The seven actions#

Action	Effect	Extra field
`tenant_halt`	Marks the tenant halted in maintenance state; activates maintenance if any tenant is halted	—
`tenant_resume`	Clears the tenant's halted state	—
`environment_halt`	Sets the named environment to `halted` and records `haltedAt`/`haltedBy`	`environmentKey` (required)
`environment_resume`	Returns the named environment to `active`	`environmentKey` (required)
`connector_pause`	Forces matching connector capability policies to `observe` mode (no enforcement-side effects)	`targetRef` = `connector` or `connector:capability`
`connector_resume`	Returns matching connector capability policies to `review` mode	`targetRef` = `connector` or `connector:capability`
`token_revoke`	Revokes the referenced API credential and writes a credential-event	`targetRef` = credential id

bash

# Halt the whole tenant
curl -X POST https://api.intended.so/admin/emergency-controls/tenant_halt \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "reason": "Containment for INC-2026-0342"
  }'

# Revoke a compromised credential
curl -X POST https://api.intended.so/admin/emergency-controls/token_revoke \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "targetRef": "cred_123",
    "reason": "Credential compromise suspected (INC-2026-0342)"
  }'

The emergency event ledger#

Each invocation creates an emergencyControlEvent with: action, status (executed · failed · reverted), environmentKey, targetRef, reason, requestedBy, metadata, and timestamps. The event is written whether or not the underlying mutation succeeded — a failed action records status: failed with the error in its metadata, so there is no silent failure. These events appear in GET /admin/emergency-controls and flow into the trust overview's emergencyEventCount7d and into audit evidence exports.

Failure modes#

Status	Code	Cause
400	`INVALID_ADMIN_EMERGENCY_CONTROL_ACTION_REQUEST`	Unknown action, missing `reason`, or malformed body
400	`ENVIRONMENT_KEY_REQUIRED`	`environment_halt`/`resume` without `environmentKey`
400	`TARGET_REF_REQUIRED` / `INVALID_TARGET_REF`	`connector_*` / `token_revoke` without a valid `targetRef`
401	`UNAUTHENTICATED_ACTOR`	No resolvable actor on the request
403	`TENANT_MISMATCH`	`x-tenant-id` ≠ body `tenantId`
403	`FORBIDDEN` (+ `permission: "emergency:invoke"`)	Role is not `owner`/`admin`
404	`CREDENTIAL_NOT_FOUND`	`token_revoke` target credential is not in this tenant

Targets that match nothing fail closed and are recorded

If a connector_* or environment_* action matches no records (e.g. an unknown connector or environment), the action is recorded as failed with the specific error in its metadata rather than reported as a success. Read the returned event's status and metadata.error to confirm the action took effect.