Skip to main content
You already have a firewall policy you trust in staging, and you want a second one for production with two rules changed — or you want to tighten the live policy without losing track of what changed. Both are policy-lifecycle moves: stand up a second policy as a starting point, and lean on the version that bumps on every update to know your change propagated. This page is the lifecycle reference — branch, version, default, and enable/disable/delete. For first-time setup see Create & attach; for the rule grammar see Firewall Rules.
All policy management happens in the console (or the /api/workspace/firewall/* management routes, which authenticate with your session / access token — not a relay sk-orca-… key). Only your agent’s /v1/* calls use the relay key. Creating, editing, and defaulting a policy are Developer+ actions; reading the policy list and its version is open to every Member.

​
1. Branch your posture into a second policy

There is no “fork” verdict or copy button — a policy name is unique per workspace, so the pattern is to stand up a second, independently-versioned policy and diverge it freely without touching the original. Two ways to seed it:
1

Create the new policy, then author its rules

Open Security → Firewall → Policies → New policy. A new policy is created with no rules and your chosen default_verdict — author its rules in the editor (or copy a few over from the source policy by hand). Give it a workspace-unique name (e.g. prod-firewall next to staging-firewall).
2

Or apply a use-case template

The Templates gallery (POST /api/workspace/firewall/templates/apply) creates one new policy plus all its rules in a single transaction — Coding, Support, RAG, Data, DevOps, Browser, or Baseline. Faster than hand-authoring when a template matches.
3

Diverge and attach

Edit the new policy’s rules — tighten the destructive-shell deny, swap an egress allow-list host — then attach it to the production key via firewall_policy_id, or mark it the workspace default. The source policy is untouched.
A second policy is the safe way to test a riskier posture. Stand one up, turn on shadow mode on it, attach it to one canary key, and watch the events feed — the production policy on every other key keeps enforcing unchanged.
Each policy carries its own provenance, its own attached-key count, and its own version line.

​
2. The version that bumps on every update

Every firewall policy has a version integer. It starts at 1 when the policy is created and increments by one on every update — a rule edit, a default-verdict change, an enable/disable toggle, a shadow-mode flip. It is monotonic and never resets. 
// GET /api/workspace/firewall/policies/:id  → (abridged)
{
  "id": 42,
  "name": "prod-firewall",
  "enabled": true,
  "is_default": true,
  "default_verdict": "audit",
  "shadow_mode": false,
  "version": 7,          // bumped from 6 → 7 by your last save
  "rule_count": 11,
  "attached_key_count": 3
}
The version is your propagation signal: the gateway caches resolved policies briefly, and every save invalidates that cache so your edit takes effect on attached keys within seconds — no redeploy, no agent-code change. The version doesn’t drive the cache; it’s a monotonic change counter you read back. When you save a policy and want to confirm the change is live, re-read the policy and check that version advanced.
The policy version is a change counter, not a restore point. It tells you that the policy changed and lets the gateway propagate the edit — it is not a per-version diff or rollback. For full versioned history with diff and one-click revert, that capability lives on Guardrails: GET /api/guardrail/:id/history, …/history/diff, and POST /api/guardrail/:id/revert (revert is Developer+). For firewall policies, your audit trail and keeping a demoted known-good policy in the list are how you preserve a restore point — see §5.

​
3. Set and move the workspace default

A workspace can mark one policy as the default. Every key without its own firewall_policy_id resolves to it (resolution order).
  • Edit a policy and set it as the workspace default. Promoting a new default demotes the old one in the same transaction — there is never a window with two defaults, and never a window with none mid-swap.
  • Standing up a second policy is a clean way to roll the default forward: build the new policy, adjust, validate under shadow mode, then promote it. The old default stays in the list, demoted, as your fallback.
Moving the default changes enforcement for every unattached key at once. If the new default tightens the default_verdict to deny, calls your rules don’t explicitly allow start blocking immediately. Roll a new default out behind shadow mode and watch Events before you promote it.

​
4. Enable, disable, and delete

Toggling Enabled off stops a policy from resolving. But remember the firewall fall-through: a key whose attached policy is disabled falls back to the workspace default — disabling does not take the key out of firewall scope. To remove a key from enforcement, detach it (set firewall_policy_id to 0), don’t just disable its policy. (This differs from guardrails, where a disabled attachment resolves to none.)
DELETE /api/workspace/firewall/policies/:id (Developer+) removes a policy — but returns 409 if any key still references it. Detach or re-point those keys first, then delete. This guard is why standing up a second policy, not in-place rewriting, is the safer way to evolve a policy that live keys depend on.
A policy name is unique within a workspace, so a second policy needs a new name. Use a convention that survives the lifecycle — staging-firewall / prod-firewall, or a date suffix — rather than policy-copy-2.

​
5. Audit trail

Every policy create, update (which includes a default-promotion or a shadow-mode flip), and delete writes an audit row — both a workspace row and a central admin row — after the change commits. A failed save (duplicate name, invalid verdict) writes nothing. Rule blobs and secrets are never written to the audit log. So even though firewall policies don’t carry a diff-and-revert history of their own, the audit trail tells you who changed which policy, when, and the monotonic version tells you how many times it has changed. Pair that with keeping a demoted, known-good policy in the list, and you have a practical restore path.

​
6. Lifecycle at a glance

ActionRouteRole
List policies (+ version, counts)GET /api/workspace/firewall/policiesMember
Read one policyGET /api/workspace/firewall/policies/:idMember
Create policy (no rules)POST /api/workspace/firewall/policiesDeveloper+
Apply a template (policy + rules)POST /api/workspace/firewall/templates/applyDeveloper+
Update (bumps version)PUT /api/workspace/firewall/policiesDeveloper+
Delete (409 if keys attached)DELETE /api/workspace/firewall/policies/:idDeveloper+
Before relying on a new or freshly-promoted policy, dry-run it in the sandbox Test tab — it returns the verdict, the matched rule, and the reason without dispatching anything. See Test rules.

​
Where to go next

Create & attach

The first-time setup path — create a policy and point a key at it.

Shadow mode

Roll a new or re-defaulted policy out without changing live traffic.

Firewall + Guardrails

How action policies compose with text guardrails — and where versioned revert lives.

Scope: keys, policies, workspaces

How attachment and the workspace default resolve.