# Surface reference

> Field reference for the top-level AgentSurface configuration.
The AgentSurface is the top-level configuration and runtime entity in the Agent Gateway. One surface represents one managed agent’s full surface area: how it is reached, where it routes, what identity it carries, and what it can call out to.

For the complete sub-component field references, see [Access Point](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md), [Target](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/target.md), [Transit Points](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/transit-points.md), and [Variants](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/variants.md).

## Top-level fields

| Field | Type | Required | Default | Description |
| Surface ID | string | Read-only | Auto-assigned | Unique identifier assigned at creation. Shown in edit mode. Never changes after creation. |
| Name | string | Yes | — | Human-readable name. Appears in the dashboard, logs, and metrics. |
| Description | string | No | — | Optional description. |
| Protocol | [Protocol options](#protocol-options) | Yes | A2A / UCP | Agent protocol for both inbound and target communication. Locked once elements are added to the canvas. |
| Surface enabled | toggle | No | On | When off, the surface returns HTTP 503 to all inbound requests. |
| Issuer | string | No | — | Owning issuer for this surface. Drives trust-registry injection defaults. References a Department record, not the Issuer entity at Identity → Issuers. |
| Tags | string[] | No | — | Labels for grouping, filtering, and search. |
| Publish to Gateway DID document | toggle | No | Off | When on, advertises this surface in the gateway’s DID document. |
| Gateway DID injection | toggle | No | Off | When on, injects a did:webvh identity on every outbound request from this surface. See [Gateway DID injection settings](#gateway-did-injection-settings). |
| Terminate trace at egress | toggle | No | Off | Keeps the incoming trace ID for this surface’s own audit; forwards a fresh trace ID downstream. Prevents the trace from crossing to the next gateway or agent. |
| Access Point | [Access Point settings](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md) | Yes | — | Inbound configuration: how callers reach this agent. |
| Managed Agent | [Managed Agent settings](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/target.md) | Yes | — | The single upstream destination: the managed agent backend. |
| Outbound Listener | [Transit Point settings](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/transit-points.md) | No | — | Agent-initiated outbound routes. |
| Variants | [Variants](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/variants.md) | No | — | Named surface variations selectable at request time via $alias in the URL. Use Promote to default in the Variants panel to set the active default variant. |
| Agent Identity | [Agent Identity](#agent-identity) | No | — | Three independent identity resolution slots covering each pipeline edge. |
| Credential Delegation | — | No | — | Outbound credential bindings injected when the managed agent forwards a request upstream. Added as a Credential Delegation canvas element on the Managed Agent → External edge. |

## Protocol options

Selected when creating the surface and locked once elements are added to the canvas.

| Protocol | Description |
| A2A / UCP | Agent-to-Agent protocol (JSON-RPC 2.0 with A2A extensions). Default. Use for direct agent-to-agent communication and UCP extension flows. |
| AP2 | Agent Payments Protocol. Extends A2A with Verifiable Credential and VP transformation for payment-agnostic financial transactions. |
| MCP | Model Context Protocol (JSON-RPC 2.0). Use when connecting AI models to external tools and data sources. |

## Gateway DID injection settings

These fields appear in the Gateway DID Injection section of the surface panel when Gateway DID injection is enabled.

| Setting | Required | Description |
| Identity ID | No | Bind to an existing managed identity by its UUID. Leave blank to create a new identity automatically. |
| Auto-create identity if it does not exist | No | When on, the gateway creates a new managed identity if the specified Identity ID does not exist. Requires Identity ID to be set. |
| DID Path | No | Custom path segment for the did:webvh DID. Defaults to the surface name when blank. |
| Injection Mode | Yes (when enabled) | How the DID is injected into outbound requests. See [Injection modes](#injection-modes). |

### Injection modes

| Mode | Description |
| Header | Injects the DID as the X-DID-Identity HTTP header. |
| Signed Header | Injects a signed DID assertion as the X-DID-Signed-Identity HTTP header. |
| Protocol Native | Injects the DID using the protocol’s native extension mechanism: A2A extension or MCP _meta field. |

## Agent Identity

Three independent identity slots, one per pipeline edge. Each slot defines how the gateway derives an agent DID on that edge. Configure each slot by adding an Identity canvas element to the corresponding edge.

| Slot | Pipeline edge | Purpose |
| Caller (inbound) | Caller → Access Point | Extracts the caller agent’s identity from the inbound request. |
| Managed agent (protected) | Managed agent → Access Point response | Extracts the managed agent’s identity from the response body. |
| External agent | External target → Transit Point response | Extracts the external agent’s identity from an outbound response. |

## Identity slot modes

Each slot can be configured in one of the following modes:

| Mode | Description |
| From Payload | Parses identity metadata from the request or response body. Requires the agent-identity/v1 extension on inbound A2A / MCP traffic. |
| From API Key | Derives the DID from the validated API key credential. Rotating the key produces the same DID. |
| From mTLS certificate | Derives the DID from the client certificate presented during the request. |
| Static DID | Uses a fixed, pre-known DID for all requests through this slot. |
| From JWT Claims | Extracts the DID from a named JWT claim. Requires JWT Bearer authentication on the same surface. Only available on the inbound pipeline. |

## Policy definition

The Policy Definition settings attach an OPA policy to a surface component. Used on the [Access Point](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md), [Managed Agent](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/target.md), and [Transit Points](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/transit-points.md).

| Field | Type | Required | Default | Description |
| Policy Definition | string | Yes | — | ID of the OPA policy definition in the policy store. |
| Require agent context | bool | No | false | When enabled, the pipeline fetches the target’s agent card and queries the trust registry before evaluating this policy, populating input.agent in the OPA input. Adds latency; only enable when the policy uses input.agent. |

## Rate limit

The Rate Limit settings control inbound and outbound request throttling. Used on the [Access Point](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md) and [Transit Points](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/transit-points.md).

| Field | Type | Required | Description |
|—|—|—|
| Max requests per window | integer | Yes | Maximum number of requests allowed within the rate limit window. |
| Window (seconds) | integer | Yes | Duration of the rate limit window in seconds. |

## Related

- [Access Point reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md): Inbound routing and caller authentication fields.

- [Target reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/target.md): Upstream endpoint and OPA policy fields.

- [Variants reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/variants.md): Per-variant override model.

- [Surfaces concept model](/products/affinidi-trust-fabric/agent-gateway/concepts/surfaces.md): How surfaces work at runtime.