OPA policies reference

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

• The Policy element: which canvas slots accept a policy and how to configure the element on a surface.
• 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 via Regorus. 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 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 (authorization, cookie, any header containing token) are stripped before policy evaluation. 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 when the caller is authenticated. Absent when the surface has no Caller Context element or when the request carries no credentials.

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"]
  }
}

input.mcp

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

input.a2a

Present on A2A and AP2 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 authenticated: the surface has a Caller Context element and the request carries valid credentials.
• 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 headers whose names include authorization, cookie, or token, matched case-insensitively. These are stripped at policy input construction time. Policies cannot read bearer tokens, API key header values, or session cookies from input.http.headers. Use input.source_auth for authenticated identity information instead.

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.