Agent ID Policies
Last Modified: 2026-11-19

Agent ID Policies

Roles decide which tools a person can reach. Policies go one step further and decide whether each individual call is allowed, for example depending on which agent is making it or what it is asking for. Policies are rules evaluated at the gateway for every call an agent makes. A policy can be tenant-wide or assigned to specific gateways. Policies are written in Cedar, an open-source policy language. Each policy is a permit or forbid statement with conditions on who is calling (principal), what they are doing (action), and what they are calling (resource). Order does not matter: if any forbid policy matches a call, the call is denied. Policies are written once for your organization and published to the gateways you choose; changes are listed in Publish management first, so you can review what will change, and on which gateway, before it takes effect.

The Policies page has three tabs:

  • Policies: This lists your custom Cedar rules together with the built-in System Defaults.

  • Blocked agents: This lists agents and NHIs currently blocked at the gateway, separate from the rule list.

Use the Actions menu at the end of a policy's row to Edit policy, Duplicate policy, Disable policy, or Delete policy. To act on several policies at once, select them and choose Assign to gateway, Set to audit, Enable, Disable, Delete, or Export selected.

The System Defaults section lists two platform-wide behaviors, both set to All Gateways, that are applied before any custom policy is evaluated: Default Tool Execution (Critical, Fail closed: requests that do not match a policy are denied) and Default Tool Discovery (High, Restricted: tools stay hidden until a policy explicitly authorizes them). Because of these defaults, agents cannot see or call any tool until a policy permits it.

For example, the following rule permits calling the list_issues tool on the linear-mcp resource, but only after a human approves it over an out-of-band (backchannel) channel:

@requireApproval("backchannel")
@approver("user:alan.easow@example.com")
permit(
    principal,
    action == McpGateway::Action::"call",
    resource
) when {
    resource.namespace == "linear-mcp" && resource.name == "list_issues"
};

The @requireApproval and @approver annotations are what route a matching call to the Human-in-the-Loop Approvals queue instead of allowing or blocking it outright.

Three short examples show the three effects a rule can have (replace the namespace, tool name, and approver with your own values):

// Allow a call
permit (principal, action, resource)
when { resource.namespace == "deepwiki" && resource.name == "ask_question" };
// Deny a call
forbid (principal, action, resource)
when { resource.namespace == "billing" && resource.name == "export_all" };
// Require approval before a call proceeds
@requireApproval("inline_form")
permit (principal, action, resource)
when { resource.namespace == "billing" && resource.name == "refund_payment" };

Procedure 

  1. On the Policies page, click New Policy.
  2. Under Assigned gateways, select the gateways this policy applies to.
  3. Choose Natural language to describe the rule and click Generate policy, or choose Manual to write it yourself.
  4. For Manual, enter a Policy Name, an optional Description, and a Severity (Critical, High, Medium, or Low).
  5. Under State on Save, choose Enable, Audit-only mode (logs what will happen without blocking), or Disable.
  6. Write the rule in the Policy editor, or click Templates to start from an example.
  7. Click Create policy.

Results 

The policy is queued as a pending change; it takes effect once published. For more information, see Publishing Configuration Changes).

Note:  A forbid that matches a call always wins, whatever other policies define.