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.
On this page
Start here
Freeze risky gateway execution immediately while operators investigate. Choose the narrowest scope: one service agent, one connector, or the workspace. Paused and archived states are broader controls with their own precedence.
Before you begin
- Workspace owner or admin access and a clear incident reason
- The affected target plus an expiry decision and named reviewer
Put it into practice
-
Contain with the narrowest scope
Create the freeze with a specific, audit-ready reason and optional future expires_at. Record its ID and verify the response reports it as active.
-
Confirm enforcement
Run a safe policy simulation or observe the next relevant authorization. A freeze must short-circuit before grants and policies, and machine traffic sees workspace state where applicable.
-
Investigate, then thaw
Keep operators working while execution is stopped. Lift manually when the cause is resolved or allow expiry, then confirm the thaw event and audit record before resuming automation.
Affected authorization decisions are denied with a frozen decision path, queued approvals cannot execute past the new check, and lifting or expiry restores only the intended scope with a complete audit trail.
01 Freeze scopes
detailsworkspace
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
detailsA 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.
Create body
POST /api/v1/operator/gateway_freezes requires owner or admin manage. Body fields: scope_type (workspace, connector, or service_agent), reason, optional expires_at, plus connector_id when scope_type is connector and service_agent_id when scope_type is service_agent. The JSON includes a derived active flag: it is false after a lift or after expires_at even before the sweeper stamps lifted_at. The operator screen is /app/gateway.
Auto-thaw
An expired freeze stops blocking immediately, because active-freeze checks exclude an expires_at in the past. A sweeper runs every minute to stamp lifted_at, write the audit record, and broadcast 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 |
05 Machine traffic gates
referencePrecedence: 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
examplePOST /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
detailsgateway.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.
Troubleshooting
- The response names another workspace state
- Archived takes precedence over paused, which takes precedence over frozen. Invalid or revoked credentials can also fail before workspace-state reporting.
- The displayed freeze differs from the workspace freeze
- When several active freezes apply, reporting prefers service_agent, then connector, then workspace. Check all active scopes before lifting anything.
- An expired freeze still has no lifted_at
- Expiry stops blocking immediately. The one-minute sweeper records lifted_at, audit, and gateway.thawed shortly afterward.