Trust registries

A Trust Registry is a directory of identities and an authorisation service for a trust network. It publishes and resolves DIDs, and it answers authorisation questions, for example whether a given agent is permitted to perform a particular action on a particular resource.

The Agent Gateway queries trust registries using a standard query protocol during its trust checks. Connecting to a trust registry enables the gateway to:

• Publish its own identity so peers can discover it.
• Resolve peers’ identities and confirm they are genuine.
• Check authorisations as part of deciding whether a request may proceed.

The gateway connects to a trust registry via a DIDComm handshake and queries it using TRQP. The registry responds with a boolean verdict indicating whether the queried entity is recognised or authorised.

Connecting a trust registry

A trust registry is added in the same way as a gateway, by accepting an out-of-band invitation. The form asks for:

• Name: Human-readable label for this registry connection.
• Description (optional): Notes on the registry’s purpose or environment.
• OOB URL: The out-of-band invitation URL from the registry.
• DID Method (optional): Preferred DID method for this connection (did:peer or did:web).

On submission the gateway begins a handshake and the connection progresses through its states.

Trust registry connection status

Each trust registry connection has a status that reflects the current handshake and operational state:

A connection attempt that does not complete transitions to Failed from either Connecting or Awaiting Approval.

What you can do

For each trust registry you can:

• View its records: the recognition and authorisation entries it holds.
• Reconnect: if it has dropped or failed to re-establish the connection.
• Delete the connection: when the registry is no longer needed.

How the gateway connects to a trust registry

The gateway establishes a live DIDComm connection to each trust registry using an OOB (Out-of-Band) invitation URL. The trust registry administrator provides this URL from the registry’s connection point. When you add a trust registry in the dashboard, the gateway parses the OOB invitation to discover the registry’s DIDComm endpoint and mediator, creates a per-registry identity (a did:web or did:peer DID specific to this connection), sends a setup message and waits for the registry administrator to approve the connection, then transitions to Connected status once the registry accepts the handshake.

Once the connection status is Connected, the registry is available for use in surface configuration and the gateway can issue TRQP queries to it.

How the registry lookup works

The trust registry holds authoritative records. Each record is identified by the combination of four fields:

The gateway sends a TRQP query containing these four fields to the connected trust registry over DIDComm. The registry evaluates the query and responds with a boolean verdict: recognized: true/false for a recognition query, or authorized: true/false for an authorisation query. The gateway writes the result into input.trust_check_results for OPA evaluation; OPA then decides whether the request may proceed.

The gateway supports two TRQP query types:

• Recognition: asks whether authority_id recognises entity_id as belonging to its trust network. When action and resource are not configured on the element, the gateway fills in wire defaults ("is" and "ownedAgent") so 4-tuple-indexed registries still match the record.
• Authorization: asks whether entity_id is authorised to perform action on resource. Both fields must be set explicitly on the element — the gateway does not supply defaults for authorisation queries.

Trust extension fields in the message

When an agent sends a message that carries trust registry metadata, the trust extension is identified by the URI https://fabric.affinidi.io/extensions/trust-registry. The extension includes four fields that identify the parties involved.

For a complete field reference, see Trust registry reference.

How it is used

When a message arrives at an access point of the managed agent with Trust Check elements configured, the gateway follows this sequence:

Issuers and how trust registries link to managed agents

The trust registry connection alone does not activate trust verification on a surface. The link between a connected trust registry and a surface is established through an Issuer.

An Issuer is a gateway entity with its own auto-generated DID. When you create an Issuer, you optionally link it to a connected trust registry and provide an Authority DID (the parent organisation DID that vouches for the issuer). The gateway registers the issuer in the selected trust registry via DIDComm.

Once an Issuer is created and registered:

1. Open the surface in the canvas and click the Surface element (the blue container) to open its configuration panel.
2. Select the Issuer from the Issuer dropdown. This assigns the owning issuer to the surface and drives trust-registry injection defaults.
3. Add a Trust Registry element to the canvas and set the Action to inject or both. Configure the Injection Direction (inbound, outbound, or both).
4. The gateway automatically resolves the provider_did and trust_registry_did from the surface’s assigned issuer and gateway identity. No manual DID entry is required.

If the Issuer’s trust registry registration status is Failed, use the Retry TR Registration button on the Issuer record to re-attempt registration before assigning the Issuer to a surface.

Where it appears in the dashboard

Trust registry configuration touches three areas of the dashboard:

• Trust Registries section: Add and manage trust registry connections. Each entry shows the connection status badge and a heartbeat button (when connected).
• Identities → Issuers: Create Issuers, link them to a connected trust registry, and check their TR Registration Status.
• Surface canvas → Surface element: Assign an Issuer to the surface. The selected issuer drives trust-registry injection defaults for all Trust Registry elements on the canvas.
• Surface canvas → Trust Registry element: Configure the trust registry action (verify, inject, or both) and injection direction.

Remote identities verified through a trust registry appear on the Identities tab with a VERIFIED badge.

Verification modes

Surfaces support two verification modes.

Source mode (the default) validates the incoming agent. The gateway extracts trust registry metadata from the sender’s message and queries the registry to verify the sender’s authorisation.

Target mode validates against the receiving agent’s card. The gateway fetches the target agent’s card, extracts its trust registry data, and verifies that the sender is authorised in that registry.

Related

• Add a trust registry: Step-by-step guide to connecting a trust registry via OOB invitation and assigning it to a surface.
• Enable agent identity on a surface: Configure inbound identity that trust registries can verify.
• Trust registry reference: Complete field definitions for the trust registry object.
• Agent identity and DIDs: How agent DIDs are assigned and verified.