OPA 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.

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 the request carries no credentials.

The shape depends on the authentication method, indicated by the method field:

JWT bearer: caller authenticated with a validated JWT:

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

API key: caller authenticated with a surface-scoped API key:

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

DID auth: caller authenticated with a DID-based credential:

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

mTLS: caller 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. Built from the original request body before identity injection, so it 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 normalize_caller_did runs, which promotes the gateway-derived caller DID into input.agent.did when no trust-registry extension is in the payload. 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. Used in gateway-to-gateway trust chains.

input.trust_check_results

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

Each leg carries results in the order the elements were configured.

{
  "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:

For the complete list of error.code values, their categories, and field-population rules, see Trust Check element reference — Error codes.

input.metadata

Present when Custom 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

✓ = present when conditions met. — = never present on this path.

MCP tool policy input

MCP tool policies use a different input struct from gateway and surface policies. The package is still channel.policy, but the field paths are different.

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 (case-insensitive). 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.