# Metadata elements

> Field reference for the Metadata Injection and Metadata Extraction canvas elements: inject fixed key/value pairs into headers or protocol extensions, and map HTTP headers into protocol metadata.

Two canvas elements manipulate metadata in the request pipeline. Metadata Injection adds fixed key/value pairs to requests or responses before they are forwarded. Metadata Extraction reads selected HTTP headers and normalises their values into the protocol metadata namespace before identity, policy, and Trust Check controls run.

## Metadata Injection

The Metadata Injection element adds a fixed set of key/value pairs to every request or response flowing through the surface at the configured location. The upstream agent receives the injected metadata without any indication of its origin.

The direction (request or response) is set by the edge you drop the element on. One element per direction. Both can coexist on the same surface.

### Fields

| Field | Type | Required | Default | Description |
| Entries | array | Yes | — | Key/value pairs to inject. At least one entry is required. |
| Key | string | Yes (per entry) | — | The header name, extension field name, body key, or query parameter name. |
| Value | string | Yes (per entry) | — | The value to inject. Supports secret references and dynamic tokens; see the Dynamic values reference below. |
| Target | select | No (per entry) | HTTP Header | Where this entry is placed. Options: HTTP Header, Protocol Extension (A2A / AP2 extension block), Body (JSON merge) (merged into the top-level JSON payload), Query Parameter. |

### Dynamic values

Use these tokens in any entry’s Value field. The gateway resolves them at injection time.

| Token | Resolved value |
| $REQUEST_ID | Current request trace ID. |
| $TIMESTAMP | Injection-time UTC timestamp. |
| $SURFACE_ID | Agent Surface ID. |
| $SECRET:id | Value of the secret with the given ID. Use the key icon next to the value input to select a secret from the configured list. |

## Metadata Extraction

The Metadata Extraction element reads values from selected HTTP request headers and normalises them into the protocol metadata namespace before identity extraction, policy evaluation, Trust Check, Workload Binding, and forwarding controls run. Use it when an upstream caller or managed agent presents metadata-like evidence only as HTTP headers but downstream controls need to read it from the protocol metadata namespace.
Note

This element is only visible in the element palette when the copilot_integration feature flag is enabled on your gateway.

Applies to the request direction only. Drop it on a Managed Agent → A2A or AP2 Transit Point request edge. The header mapping editor is also available on the Access Point → Managed Agent request edge when the surface uses A2A or AP2 protocol; on MCP surfaces that edge disables the editor and no extraction occurs.

### Fields

#### Header mapping

| Field | Type | Required | Default | Description |
| Namespace URI | string | No | https://fabric.affinidi.io/extensions/header-metadata/v1 | The protocol metadata namespace the extracted headers are written into. If Identity or another element reads this mapped metadata, configure it with the same URI. |
| Strip mapped headers | bool | No | true | When on, the gateway removes the source HTTP header from the request after extracting its value into metadata. |

#### Header mapping rows

Each row maps one HTTP header to one protocol metadata field.

| Field | Type | Required | Default | Description |
| Header | string | Yes (per row) | — | The HTTP request header name to read from (for example X-Agent-Id). |
| Field | string | Yes (per row) | — | The metadata field name to write to within the extension block. |

## Related

- [Identity element](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/identity.md): the From Payload extraction strategy can read from the metadata populated by Metadata Extraction.

- [Managed Agent reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/managed-agent.md): canvas element overview.