Policies

Overview

A Checkpoint policy is a Cedar policy that decides what happens when the Gateway or Middleware classifies a request. You author policies in Compose: describe the rule in plain language, Checkpoint compiles it to Cedar, you dry-run it against real traffic, then Authorize & deploy.

How policies evaluate

Checkpoint uses an allow-by-default, carve-out posture. Every deployed policy starts from a baseline that permits all traffic:

@id("baseline-allow")
@verdict("ALLOW")
permit ( principal, action, resource );

Each rule you add is a forbid that carves out a stricter verdict — BLOCK, CHALLENGE, REDIRECT, or INSTRUCT — for the requests it matches. Cedar is forbid-overrides: when more than one rule applies to a request, the restriction wins. So a policy reads as "allow everything, except…" — you never enumerate the traffic you want to let through.

A rule matches on facts the detection engine supplies about each request:

principal.category values

principal.category is a projection of the detection class, not the class itself. The engine emits exactly five values:

principal.name is sometimes a group label

Named vendors come through as themselves — GPTBot, ClaudeBot, ChatGPT, Googlebot. But the non-AI patterns match to a shared label, so a whole family of tools collapses onto one name:

principal.reputation is not populated yet

On scales, for when reputation does land: registry and Bouncer surfaces score agent reputation 0–100 (thresholds like 60), while the engine consumes a normalized 0.0–1.0 score for the principal.reputation fact. Both are correct at their layer — write Cedar thresholds as decimals (decimal("0.7")), and leave translating between the scales to the reputation service rather than comparing numbers across layers.

Use when { … } for the facts that make a rule apply and unless { … } for carve-outs (for example, exempting an agent that presents a verified delegation).

Authoring in Compose

Compose (Policy → Compose, /policy/compose) turns a plain-language description into a reviewable Cedar policy.

You describe the rule in plain language (⌘⏎ compiles), review what it emitted, dry-run it, then deploy. Compose renders the generated rules as editable sentence chips alongside the raw Cedar — what you see is what runs, and you can hand-edit the Cedar directly. Run dry test replays the policy against representative agents, or your last 7 days of traffic, through the real engine (dry run · no traffic affected) and reports the verdict and reason per request. Authorize & deploy promotes it to production, enforcing on the gateway within about a minute.

For the click-by-click walkthrough, see the Write and deploy a policy cookbook.

Draft vs. deployed

Save as draft (and edits made on a policy's detail page) update the draft only — the gateway keeps enforcing the last deployed version until you redeploy. A live policy shows an ● Enforcing on the gateway badge; a policy with saved-but-not-redeployed changes shows ● Enforcing a previous version — redeploy to apply. Deploying is what flips a project into engine enforcement.

Managing a policy

The policy list lives at Policy (/policy). Open a policy for its detail page, which has four tabs:

Verdicts

A rule's @verdict(...) sets what happens to a matching request:

These map to the engine's five-verdict Decision (Permit / Block / Challenge / Redirect / Instruct), orthogonal to the enforce/observe mode covered in Enforce vs. observe below. (Stored decisions may still show the legacy wire values allow and log from before this vocabulary split — read allow as Permit and log as Permit + Observe mode. There is no REWRITE verdict.)

The HTTP response a verdict produces depends on which surface enforces it, so the two shipped surfaces are listed separately:

Choosing a verdict

Match the verdict to the threat model of the endpoint. Because policies are allow-by-default, you write rules for the traffic you want to restrict.

BLOCK

Refuse to serve the request (a 403 at the Gateway; see the table above for the middleware shape). Use it when the endpoint is strictly not for agents — competitor scraping of proprietary content, admin surfaces, endpoints that cost money per request — or as a short-term block during an incident (e.g. an AI crawler hammering your origin).

Not a good fit for a general content site: a blanket block will catch legitimate AI agents your users are delegating to. Prefer REDIRECT or INSTRUCT for soft-to-cryptographic enforcement.

REDIRECT

Return a 302 to a URL you choose — a consent page, a sign-in flow, a pricing page, or your hosted Bouncer consent. It's soft enforcement: "you can get what you need, just through this other flow." The target accepts absolute URLs (https://acme.com/for-ai) and same-origin paths (/ai-welcome), so one policy can cover staging and production.

Not a good fit for sensitive endpoints — a 302 is trivial for a sophisticated agent to ignore. Use INSTRUCT there.

CHALLENGE

Require the agent to satisfy a consent or approval step before proceeding. Two shapes:

• Consent — the agent must carry the scopes the rule demands (@scopes(...) + a context.granted_scopes carve-out). Use it to gate specific tools or data behind explicit user consent.
• Step-up approval — the request must collect a quorum of approvals from named approvers (@approvers(...) + @quorum("N")). Use it for high-stakes actions like fund transfers.

INSTRUCT

Return a KYA-OS challenge that requires a cryptographic identity on retry. Use it for sensitive work — payments, data exports, authenticated APIs, admin actions — where you want cryptographic assurance rather than best-effort detection. It is bypass-proof for agents that cannot forge a valid signature, and it defeats tool-delegation evasion (a request proxied through a third-party tool cannot carry the proof).

The idea behind the dual envelope is that AI-agent fetchers collapse 4xx responses and never show the model the body, so a plain 401 is invisible to exactly the caller it is meant to instruct. A cooperative, self-identifying agent therefore gets a body-readable 200 carrying the same body and no WWW-Authenticate. Envelope selection is a cooperative-UX bridge, never an access control: access stays gated on detection plus delegation verification either way.

INSTRUCT by surface

Only two of the five surfaces implement that negotiation. Deploy against the surface you actually run, not against a uniform story:

Two consequences worth stating plainly. The Gateway does not negotiate for INSTRUCT at all — its KYA_HTTP_CHALLENGE_MODE setting governs CHALLENGE only, so a cooperative agent hitting the edge still receives a 401 whose body it will not read. And .NET returns 200 unconditionally, so a client that keys off the status code will read every INSTRUCT as success; read the body or the X-Checkpoint-* headers there.

delegationChallengeMode therefore affects the three middleware rows only.

INSTRUCT is verified in-process by every runtime — Gateway and every middleware SDK — so it does not require the Gateway to be deployed. Putting the Gateway in front of your origin does add edge filtering: unverified traffic is turned away before it reaches your infrastructure, rather than reaching your application server first. Pair INSTRUCT with REDIRECT per path — INSTRUCT on /api/payments/*, REDIRECT on / — rather than as a site-wide default, so non-cooperating agents on public surfaces aren't stranded on a 401. See KYA-OS Enforcement for the full flow.

Common patterns

Real Cedar for the rules teams write most often. In Compose you'd describe these in plain language; the Cedar below is what it emits.

Block a specific agent everywhere:

@id("block-gptbot")
@verdict("BLOCK")
forbid ( principal, action, resource )
when { principal.name == "GPTBot" };

Block an agent on one path (allow it elsewhere):

@id("block-scraper-on-pricing")
@verdict("BLOCK")
forbid ( principal, action, resource )
when { resource.path like "/pricing*" && principal.name == "GPTBot" };

Redirect scrapers to an AI portal:

@id("redirect-scrapers")
@verdict("REDIRECT")
@redirect("/for-ai")
forbid ( principal, action, resource )
when { principal.category == "scraper" };

Challenge browser-automation traffic (Puppeteer, Playwright, Selenium, HeadlessChrome, webdriver, Scrapy). These all share one detected-agent name, Automation Tools, so match on principal.name — principal.category reports them as the generic bot, which would also catch Googlebot and curl:

@id("challenge-headless")
@verdict("CHALLENGE")
forbid ( principal, action, resource )
when { principal.name == "Automation Tools" };

Require consent (scopes) for an agent on a path — unless it already has them:

@id("challenge-chatgpt-on-account")
@verdict("CHALLENGE")
@scopes("settings:read settings:write")
forbid ( principal, action, resource )
when { (resource.path == "/account" || resource.path like "/account/*") && principal.name == "ChatGPT" }
unless { context.granted_scopes.contains("settings:read") && context.granted_scopes.contains("settings:write") };

Require a 2-of-N approval quorum on a sensitive action:

@verdict("CHALLENGE")
@quorum("2")
@approvers("did:web:acme:approvers:alice did:web:acme:approvers:bob")
forbid ( principal, action, resource )
when { resource.path == "/transfer" };

Exempt verified agents from a restriction — add an unless carve-out so agents that present a valid delegation pass through:

unless { principal.delegation == "verified" }

Enforce vs. observe

Enforcement has an orthogonal mode that controls whether a matched verdict actually acts:

• Observe — evaluate the policy and record what would have happened (the dashboard shows "Would have been: Block(…)"), but let every request through. Nothing is blocked.
• Enforce — apply the verdict for real, in the per-surface shape given in Verdicts above.

The recommended rollout is to deploy in observe, watch the dashboard for a week or two, then flip to enforce once the verdicts look right.

How you select the mode depends on where you enforce. Middleware SDKs take it as a config option — enforcementMode: 'observe' on withCheckpoint (see Middleware); Checkpoint for .NET reaches the same behaviour with OnAgentDetected = DetectedAction.Log. Either way the mode is recorded per detection, so the dashboard can label observed verdicts distinctly from applied ones.

The Gateway has no enforcementMode switch, and there is no log Cedar verdict — log belongs to the legacy structured path-rule layer, not to Cedar (see Observing before you enforce for how to use it there). To rehearse a Cedar rule before it takes effect on the Gateway, use Run dry test in Compose, which replays the policy against your last 7 days of traffic through the real engine without affecting any traffic — then deploy once the matched set looks right.

Identity & consent

Some Cedar facts — principal.delegation == "verified", context.granted_scopes.contains(...) — come from the identity layer, not detection. That layer — sign-in methods, providers, per-tool consent — is configured under Policy → Auth in Govern; it produces the facts your Cedar policy evaluates. A common pattern is "known, verified agents welcome; unknown agents challenged or blocked", expressed with an unless { principal.delegation == "verified" } carve-out on an otherwise-restrictive rule.

Testing a policy

1. Compose the rule and Run dry test — replays it against the real engine with no traffic affected.
2. Authorize & deploy in observe mode and review the "would have been" decisions in the dashboard.
3. Tune the rules against real traffic, then flip to enforce when you're confident.

Next Steps

• Detection in Enforce Mode — the signals behind principal.* facts
• Gateway Enforcement — the edge Gateway that enforces your policy
• Middleware Enforcement — code-based enforcement
• Monitoring — track policy decisions