Add identity and access control

Add the Identity element

Select Surfaces in the dashboard sidebar and open the surface you created.

In the element palette on the left, find the Identity element under Enhancements. Drag it onto the arrow between the Access Point and the Managed Agent nodes. The settings panel opens and shows the Inbound caller identity context block, confirming the element occupies the correct slot on the inbound request edge.

In the settings panel, locate the Identity Extraction Type dropdown and select From Payload (identity metadata).

Select Configure Fields… to open the field editor. Add a property named agentId, set its type to string, and enable the x-identity toggle on it. Fields with the x-identity toggle enabled contribute to the DID hash. Requests that supply the same agentId value always resolve to the same DID.

Close the field editor. Select the save icon in the toolbar to save the surface.

Send a test request with an identity

For A2A surfaces, declare the extension URI in message.extensions and nest the identity fields under that URI key in message.metadata. Replace <YOUR_GATEWAY_HOST> and <YOUR_SURFACE_PATH> with your values:

curl -k -X POST "https://<YOUR_GATEWAY_HOST><YOUR_SURFACE_PATH>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": "test-002",
    "params": {
      "message": {
        "role": "user",
        "messageId": "msg-002",
        "extensions": [
          "https://fabric.affinidi.io/extensions/agent-identity/v1"
        ],
        "metadata": {
          "https://fabric.affinidi.io/extensions/agent-identity/v1": {
            "agentIdentity": {
              "agentId": "my-test-agent"
            }
          }
        },
        "parts": [{ "kind": "text", "text": "Hello with identity" }]
      }
    }
  }'

Select the Monitoring tab on the surface detail page. A new identity entry should appear. Every future request with "agentId": "my-test-agent" resolves to the same DID. Requests with a different agentId value receive a separate, distinct DID.

Create a policy definition

Surface-level OPA policies are defined once and can be reused across multiple surfaces.

Select Policies in the dashboard sidebar, then select the Agent Surfaces tab. Select Define Agent Surface Policy.

Fill in the form:

In the Policy Content (Rego) editor, enter the following policy. It denies any request that does not carry a resolved agent DID:

package surface.policy

default allow = false

allow if {
    input.extension_identity.did
}

A “Valid” indicator appears next to the Policy Content (Rego) label when the syntax is accepted. Select Create.

After creating, the dashboard navigates to Settings → Policies. Return to your surface by selecting Surfaces in the sidebar and opening the surface from the list.

Assign the policy to the surface

In the element palette on the left, find the Policy element under Security & Policy. Drag it onto the arrow between the Access Point and the Managed Agent nodes.

Select the Policy element to open its settings panel. In the Policy Definition dropdown, select the policy you just created (for example, Require agent identity).

Select the save icon in the toolbar to save the surface. The policy takes effect immediately.