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.

A surface saved with an inbound policy shows it as a second Policy element on the Access Point → Managed Agent edge, evaluated before the target policy. New surfaces can’t add one in the dashboard.

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

On inbound evaluations, present whenever the surface has a Caller Context element and the request reaches policy. A caller whose credential failed reaches policy only on some Access Points; see Failed. On outbound evaluations, present when the Transit Point’s own Caller authentication verified the caller, with the same shape as on the inbound side.

The method field names the Caller Context method that verified the caller and determines the shape of the object. When a Caller Context element holds several methods, the gateway verifies each request with the method whose credential it carries, so method tells a policy which kind of credential the caller used. See How the gateway selects a method.

This rule admits every JWT caller, and only those API key callers verified against one secret:

package surface.policy

default allow := false

allow if input.source_auth.method == "jwt_bearer"

allow if {
  input.source_auth.method == "api_key"
  input.source_auth.key_name == "partner-keys"
}

JWT bearer

Callers authenticated with a validated JWT.

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

API key

Callers verified by an API Key (secret store) or API Key (provider) method. Both report method as api_key, so a policy tells them apart by key_name.

{
  "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, or who sent credentials for more than one Caller Context method, on an Access Point that hands the failure to policy. Whether a failed caller reaches policy depends on the Access Point’s state:

• Closed (the default for surfaces created from version 1.0.4, and a legacy Access Point after Close Access Point): the gateway refuses the caller with 401 and Caller credential missing or invalid before any policy runs, so policy sees no failed result.
• Public access on: the request reaches policy with method set to failed, and the surface forwards it with no asserted caller identity unless a policy denies it.
• Legacy (stored before version 1.0.4 and not yet closed): the request reaches policy with method set to failed, as on a public Access Point.

On a surface with authorization server discovery for MCP clients, a failed caller gets a 401 instead in every state. See Access Point for Public access and Close Access Point.

{
  "method": "failed",
  "attempted_method": "jwt_bearer",
  "reason": "Invalid credential: 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.transit

Present on every evaluation of a Transit Point call: the gateway, surface, per-Transit-Point and response policies, and MCP Tool Gating conditions on a Transit Point. Absent on inbound evaluations. It names two principals, each in its own field, because one call can carry both:

• input.transit.caller: the end user the transit token names, as the Access Point authenticated them. Without a valid transit token it is anonymous.
• input.transit.client: the caller the Transit Point’s own Caller authentication verified on this request. Absent when the Transit Point authenticated none.

{
  "transit": {
    "caller": {
      "verified": true,
      "verification": "transit_token",
      "identity_source": "gateway-computed",
      "user_identity_hash": "42628a381c35947c51d560b24315c5590c6f3c217701fcabd95f9fd9697bcd3f",
      "did": "did:web:caller.example.com"
    },
    "client": {
      "verification": "source_auth",
      "method": "jwt_bearer",
      "user_identity_hash": "2155543194a07922605d5396881518ffe9bc6a2dfdc434e250ea1363324f297f",
      "subject": "crm-agent"
    }
  }
}

On a Transit Point that requires the transit token, caller is the end user. On a Transit Point that authenticates its own callers, client is the agent or service that called it. A Transit Point that does both fills both. A rule about the end user reads caller, and a rule about the calling agent reads client.

To allow only calls whose end user the Access Point verified, test verified and verification:

package surface.policy

default allow := false

allow if {
    input.transit.caller.verified
    input.transit.caller.verification == "transit_token"
}

To allow only named callers on a Transit Point that authenticates its own callers, check that the Transit Point verified the caller before you match its name:

package surface.policy

default allow := false

named_callers := {"crm-agent", "billing-agent"}

allow if {
    input.transit.client.verification == "source_auth"
    named_callers[input.transit.client.subject]
}

A transit token issued for a partner’s request over Fabric reaches the agent with caller.fabric set. Check caller.fabric only as an extra rule on Transit Points that require the transit token: on one that doesn’t, an agent that sends no token leaves the rule unmatched. Which partners reach a surface is set on the Publishing tab of each remote gateway record. See Gateways.

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.