OPA policies reference

This page is the lookup reference for writing OPA (Rego) policies on the Agent Gateway. It covers:

• The Policy element: which canvas slots accept a policy and how to configure the element on a surface.
• Policy definitions: versions, dry-run testing, and deletion: the fields on the policy editor and list, the dry-run Test panel, and what the delete confirmation checks.
• Appliance-wide (global) policy enforcement: enforcing a policy definition on every gateway or every surface at once.
• Policy input reference: every field the gateway populates in the input object that Rego rules read at evaluation time.

If you are new to OPA policies on the Agent Gateway, read the OPA policies concept overview first.

The Policy element

The Policy element runs an OPA (Rego) policy against the request or response and denies it when the policy returns false. Policies run in-process. No external OPA daemon is required. Multiple Policy elements can coexist on a surface, one per slot.

The slot the element fills is determined by the edge you drop it on.

Fields

Policy definitions: versions, dry-run testing, and deletion

Every policy definition is stored as an append-only sequence of versions, not a single mutable record. Saving a change to the Rego body appends a new version and keeps every earlier one. Saving only the name, description, or enabled state updates the current version in place without creating a new one.

Content hash and version fields

The policy editor and list both show read-only fields that identify the exact Rego enforced, so a decision or an audit entry can be traced back to specific bytes even after the policy has since changed.

Dry-run testing (Test panel)

The Test (dry-run) panel appears below the Rego editor once the policy definition has been saved at least once.

The result shows an ALLOW or DENY badge, a reason when the policy defines one, and the query, version, and content hash the dry run evaluated (shown as draft instead of a version number when testing unsaved Rego).

The draft Rego and sample input are each size-capped, and a run is time-bounded, so an oversized or pathological input is rejected rather than left to run indefinitely: an oversized draft returns “Draft policy is too large to simulate”, and an oversized sample input returns “Sample input is too large to simulate”.

Delete confirmation and blast radius

Selecting the delete icon on a policy row opens a confirmation instead of deleting immediately.

• The confirmation states how many gateways (for a Gateway policy) or surfaces (for an Agent Surface policy) currently reference the policy, so you can judge the impact before committing to a delete that cannot be undone.
• This count only covers direct references within the policy’s own scope: gateways with it selected on their Global Policy tab, or surfaces with a Policy element bound to it. It does not include appliance-wide (global) enforcement. Check the policy’s Global column before deleting; a globally-enforced policy’s removal fails its entire plane closed, not only the objects the count includes. See Appliance-wide (global) policy enforcement.
• A referencing gateway or surface does not fall back to allowing traffic once its policy disappears. It fails closed: every request that policy used to evaluate is denied until a replacement is attached or the reference is removed.

Appliance-wide (global) policy enforcement

Any Gateway-type or Agent Surface-type policy definition can also be enforced across every gateway or every surface on the appliance, from the Policies list, in addition to or instead of being attached to individual objects. This is a reach setting on an existing definition, not a separate Rego scope: an appliance-wide Gateway policy still uses package gateway.policy and query path data.gateway.policy.allow, and an appliance-wide Agent Surface policy still uses package surface.policy and query path data.surface.policy.allow, exactly as described in Policy scopes and input structs.

• Appliance-wide policies evaluate deny-overrides, ahead of that plane’s own per-object policy. On an inbound direct request the order is: appliance-wide gateway policy, the gateway’s own Global Policy tab policy, appliance-wide surface policy, then the surface’s own Policy element. A deny at any stage is final.
• A Monitor assignment is evaluated and its would-be decision recorded, but it never blocks a request, so it is a way to observe a new appliance-wide rule before enforcing it.

Policy input reference

The gateway serialises request context into a structured input object before evaluating any Rego policy. Policy rules read fields from input to make access decisions. Use this reference when writing Rego rules to understand which fields are available, how authentication data appears in input.source_auth, and which fields are populated at each evaluation point.

Policy scopes and input structs

Two distinct input shapes exist. Use the correct package declaration and field paths for the scope you are writing.

Gateway and surface policies share the same PolicyInput struct and field namespace. MCP tool policies use a different struct (McpPolicyContext) with a different field layout; see MCP tool policy input.

Gateway and surface policy input (PolicyInput)

Full example

A fully-populated PolicyInput for an inbound MCP request with JWT authentication and trust registry data:

{
  "http": {
    "method": "POST",
    "path": "/v1/surfaces/my-surface/mcp",
    "headers": {
      "content-type": "application/json",
      "x-request-id": "req-abc123"
    }
  },
  "gateway": {
    "direction": "inbound"
  },
  "channel": {
    "config_id": "surface-abc123",
    "name": "my-surface"
  },
  "source_auth": {
    "method": "jwt_bearer",
    "subject": "user@example.com",
    "claims": {
      "role": "admin",
      "org": "acme-corp",
      "aud": "https://gateway.example.com"
    }
  },
  "mcp": {
    "method": "tools/call",
    "tool_name": "search",
    "params": { "query": "hello" }
  },
  "agent": {
    "did": "did:web:example.com:agent-1",
    "trust_verification": true,
    "source_trust_verification": true,
    "agent_dna": {
      "uai": "urn:uai:example.com:agent-1:v1",
      "birthEvent": { "scid": "...", "timestamp": "..." },
      "genesis": { "codeHash": "...", "genesisHash": "..." },
      "behavioral": { "behavioralHash": "..." },
      "operational": {},
      "attestations": {}
    }
  }
}

Not all fields are present on every request. See Input availability by evaluation path for when each field is populated.

input.http

Always present. Sensitive headers are stripped before policy evaluation, on inbound and outbound requests alike. Policies cannot read credential values from headers.

input.gateway

Always present. Describes the traffic direction and the identity participants.

input.channel

Always present. Identifies the surface handling the request.

input.source_auth

Present whenever the surface has a Caller Context element, whether the caller authenticated successfully or not. Absent only when the surface has no Caller Context element at all.

The method field indicates the authentication method and determines the shape of the object:

JWT bearer

Callers authenticated with a validated JWT.

{
  "method": "jwt_bearer",
  "subject": "user@example.com",
  "claims": {
    "role": "admin",
    "org": "acme-corp"
  }
}

API key

Callers authenticated with a surface-scoped API key.

{
  "method": "api_key",
  "key_name": "my-client-id"
}

DID auth

Callers authenticated with a DID-based credential.

{
  "method": "did_auth",
  "did": "did:web:example.com:caller"
}

mTLS

Callers authenticated with a mutual TLS client certificate.

{
  "method": "mtls",
  "principal": "CN=my-service,O=Example Corp",
  "fingerprint": "sha256:abc123...",
  "subject_dn": "CN=my-service,O=Example Corp",
  "issuer_dn": "CN=Example CA,O=Example Corp",
  "sans": {
    "dns": ["my-service.example.com"],
    "uri": ["spiffe://example.com/my-service"]
  }
}

Failed

Callers whose credential was missing or invalid. A failed authentication does not stop the request from reaching this evaluation point; the surface forwards it with no asserted caller identity unless a policy denies it based on this field.

{
  "method": "failed",
  "attempted_method": "jwt_bearer",
  "reason": "Token has expired"
}

input.mcp

Present on inbound MCP protocol requests only. Absent on outbound requests and non-MCP protocols.

input.a2a

Present on A2A protocol requests. It is built from the original request body before identity injection and reflects what the caller actually sent.

input.agent

Present when Extract Trust Registry Data is enabled on the surface and data was retrieved. Also present with did populated after the caller DID is resolved. Absent when neither condition applies.

input.extension_identity

Present when a verified Verifiable Presentation (VP) was included in the request body. Absent otherwise.

input.payment

Present on inbound requests where an x402 payment was verified. Absent otherwise.

input.identity_binding

Present when a verified VP from an upstream gateway was processed. Absent otherwise.

input.trust_check_results

Present when Trust Check elements are configured on the surface and at least one ran. Absent when no Trust Check elements are configured for the leg.

{
  "trust_check_results": {
    "caller": [
      {
        "id": "tc-caller-1",
        "trust_registry_id": "tr-main",
        "query_type": "recognition",
        "ok": true,
        "error": null,
        "name": "Verify caller department",
        "authority_id": "did:web:authority.example.com",
        "entity_id": "did:web:caller.example.com",
        "action": "is",
        "resource": "ownedAgent",
        "query_resolved": true
      }
    ],
    "target": []
  }
}

Each result in the array shares the same shape as the Trust Check result fields. For the complete list of error.code values and their categories, see Trust Check error codes.

input.metadata

Present when Metadata Injection rules have added metadata to the request. A flat key-value map with string keys and arbitrary JSON values.

Input availability by evaluation path

Use this table when a policy condition behaves unexpectedly. The field you are checking may simply not be populated on that evaluation path.

The four columns correspond to these evaluation paths:

• Inbound direct: a caller connects to an Access Point on this gateway.
• Inbound G2G (fabric send): the call arrives through a gateway-to-gateway Fabric tunnel, with this gateway acting as the receiving end.
• Inbound GW2 (connection point): this gateway acts as a connection point receiving a call forwarded from an upstream gateway.
• Outbound: the Managed Agent sends a request through a Transit Point to an upstream target.

Condition shorthand used in this table:

• If Caller Context configured: the surface has a Caller Context element, whether or not the request’s credentials validated.
• If TR enabled: Extract Trust Registry Data is enabled on the surface.
• If TC elements configured: at least one Trust Check element is configured for this leg.
• If VP present: a verified Verifiable Presentation was included in the request body.
• If binding VP present: a verified VP from an upstream gateway was processed at the connection point.
• If x402 verified: an x402 payment was cryptographically verified on the request.

✓ = present when the stated condition is met. — = never present on this path.

MCP tool policy input

MCP tool policies share the same package declaration (package surface.policy) and query path (data.surface.policy.allow) as surface policies, but use a different input struct (McpPolicyContext) with different field paths.

Full example

{
  "mcp": {
    "method": "search",
    "params": { "query": "hello" },
    "protocol": "json-rpc-2.0"
  },
  "jwt": {
    "role": "admin",
    "org": "acme-corp",
    "sub": "user@example.com"
  },
  "channel": {
    "name": "my-mcp-surface",
    "id": "surface-abc123",
    "protocol": "mcp"
  },
  "request": {
    "source_ip": "203.0.113.42",
    "method": "POST",
    "path": "/v1/surfaces/my-mcp-surface/mcp"
  }
}

Fields

Field name mapping from PolicyInput to McpPolicyContext

Absent fields and Rego behaviour

Fields that are not populated are omitted entirely from the JSON input. They are not set to null unless explicitly nullable in the schema above. In Rego, referencing an absent field evaluates to undefined.

A rule block where any condition is undefined does not contribute to the allow decision. When default allow = false, a rule that silently becomes undefined causes a deny.

# This rule silently denies when input.mcp is absent (non-MCP request)
allow if {
  input.mcp.tool_name == "search"
}

To write rules that handle both present and absent fields safely, use object.get or check for field existence first:

allow if {
  input.source_auth.method == "jwt_bearer"
  object.get(input.source_auth, "claims", {}).role == "admin"
}

Stripped headers

input.http.headers never contains a header named exactly authorization, proxy-authorization, cookie, or set-cookie, or any header whose name contains token, secret, credential, apikey, or api-key, matched case-insensitively. These are stripped at policy input construction time, on both inbound and outbound requests. Policies cannot read bearer tokens, API key header values, session cookies, or similarly named credential headers from input.http.headers. Use input.source_auth for authenticated identity information instead.

On a Transit Point’s outbound leg, input.http.headers carries the non-sensitive headers from the original inbound request, so a policy on that leg can check a custom header the caller sent (for example a threat-intelligence or classification header) without needing to read it from input.source_auth.

Related

• OPA policies: conceptual overview of how the gateway evaluates policies, evaluation order, and policy scopes.
• Apply OPA policies to your gateway and surfaces: create policy definitions and attach them to a gateway or surface.
• Control MCP tool access with per-tool policies: per-tool policy configuration using McpPolicyContext.
• Trust registries: how input.agent.trust_verification and input.trust_check_results are populated.
• Audit log: how policy version and content-hash evidence appears on Audit Log rows and in the event detail panel.