Platform / Gateway

Emergency freeze and workspace status

A freeze is one audited control that stops a workspace, a connector, or a single service agent from executing anything, effective on the very next authorization decision. Workspace status (paused, archived) is enforced on the same machine paths.

API docs

01 Freeze scopes

details

workspace

Refuses machine API authentication and agent socket connects for the whole workspace.

connector

Denies every authorization decision routed through that connector.

service_agent

Denies every authorization decision for that one agent.

02 Creating and lifting

details

A reason is required

reason is mandatory and must be 3 to 2,000 characters. expires_at is optional and must be in the future. Only one active freeze can exist per scope target; re-freezing an already-frozen scope returns the existing freeze rather than an error.

Auto-thaw

An expired freeze stops blocking immediately, because the active-freeze lookup already excludes freezes whose expires_at has passed. A sweeper runs every minute to record the paperwork: it stamps lifted_at, writes the audit row, and broadcasts gateway.thawed with lift_kind expired. A manual lift records the user who lifted it.

Which freeze is reported

When several freezes could apply, the narrowest wins for reporting: service_agent, then connector, then workspace.

03 Freeze API

reference

Method and path	Purpose	Success
GET /api/v1/operator/gateway_freezes	List freezes. Filters: status (active or lifted), limit (default 25, max 100).	200
POST /api/v1/operator/gateway_freezes	Create a freeze	201
POST /api/v1/operator/gateway_freezes/:id/lift	Lift a freeze. Lifting an already-lifted freeze returns 409.	200

04 What a freeze does to authorization

details

Short-circuit before policy evaluation

The authorizer returns denied with decision_path "frozen" before a single grant or policy is read, so the decision carries no matched grants and no policy. The denial is audited like any other decision, with the audit metadata carrying decision_path, freeze_id, and freeze_reason.

Approvals in flight are stopped too

No new approval request can be created while frozen, because authorization is denied before the requires-approval branch is reached. An action approved before the freeze is re-checked at execution time and fails with error code gateway_frozen rather than executing. Operators can still decide queued approvals; the stop is enforced at execution.

05 Machine traffic gates

reference

Precedence: archived, then paused, then frozen

One gate is evaluated on every machine authentication and socket connect. An archived-and-frozen workspace reports workspace_archived. Credential problems still win over workspace state: a revoked credential in a frozen workspace gets 401, not 403.

error	Status	detail
workspace_frozen	403	This workspace is frozen. Machine traffic is refused until the freeze is lifted.
workspace_paused	403	This workspace is paused. Machine traffic is refused until it is reactivated.
workspace_archived	403	This workspace is archived. Machine traffic and workspace changes are refused.
workspace_unavailable	403	This workspace is not accepting machine traffic. Returned fail-closed when the workspace cannot be resolved.

06 Frozen workspace response

example

json

POST /api/v1/traces
Authorization: Bearer {api_key}

Response 403:
{
  "type": "https://robotscenter.net/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This workspace is frozen. Machine traffic is refused until the freeze is lifted.",
  "request_id": "req-01HQ5PX7P7F4",
  "error": "workspace_frozen"
}

07 Where each surface stands

reference

Surface	Frozen or paused	Archived
Machine API (/api/v1)	403, request refused	403, request refused
Agent socket (/socket)	Connect refused with reason workspace_frozen	Connect refused with reason workspace_archived
Gateway authorization	Denied with decision_path frozen	Refused at authentication
Operator API (/api/v1/operator)	Unaffected -- operators keep working	403 workspace_archived on writes; reads still succeed
Browser console	Keeps working, with a status banner	Read-only; workspace mutations blocked

08 Realtime and alerting

details

gateway.frozen and gateway.thawed

Both events are published on the workspace topic (and on the agent topic for an agent-scoped freeze) carrying freeze_id, scope_type, connector_id, service_agent_id, reason, expires_at, created_by_id, lifted_at, lifted_by_id, and lift_kind. Both are also routed through alerting, so configured destinations are notified: critical severity on freeze, informational on thaw.

Related docs