# Trust registries > How the Agent Gateway connects to an external trust registry over DIDComm, and how it injects and verifies trust metadata on inbound requests. 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: Connecting → Awaiting Approval → Connected ↔ Disconnected A connection attempt that does not complete transitions to Failed from either Connecting or Awaiting Approval. | Status | Meaning | | Connecting | The handshake is in progress. | | Awaiting Approval | Setup has been sent and the registry’s administrator must approve. | | Connected | Fully established; identity lookups and authorisation checks can flow. | | Disconnected | Previously connected but now offline; reconnection is available. | | Failed | The connection attempt did not succeed and needs attention. | ## 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: | Field | Description | | authority_id | The DID of the organisation (authority) that grants permission. | | entity_id | The DID of the entity being checked. | | action | The action the entity is requesting permission to perform. | | resource | The resource the action applies to. | 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. | Field | Description | | trust_registry_did | The DID of the trust registry to query. Surfaces as input.agent.trust_registry_did in OPA policy input. | | agent_did | The DID of the agent making the request. Surfaces as input.agent.did and maps to entity_id in Trust Check queries. | | provider_did | The DID of the organisation that authorises the agent. Surfaces as input.agent.provider_did and is the default authority_id template value on the caller leg. | | authority_did | An optional additional authority DID. Surfaces as input.agent.authority_did. | For a complete field reference, see [Trust registry reference](/products/affinidi-trust-fabric/agent-gateway/reference/trust-registries/trust-registry.md). ## How it is used Inbound request → Extract metadata → TRQP query → Trust registry → OPA policy When a message arrives at an access point of the managed agent with Trust Check elements configured, the gateway follows this sequence: Extract The gateway builds request context from the incoming message body. When the caller includes a trust-registry extension, it populates input.agent.provider_did, input.agent.trust_registry_did, and input.agent.did. These values are then available for template resolution in the Trust Check element’s configured query parameters. Query The gateway resolves the configured query templates against the request context and sends a TRQP query to the named trust registry over the established DIDComm connection, using the resolved authority_id, entity_id, action, and resource values. All configured Trust Check elements fire in parallel. Evaluate The registry responds with a boolean verdict (recognized or authorized). The gateway writes each result into input.trust_check_results and emits a structured audit event. OPA then evaluates the policy with those results in scope — OPA, not the Trust Check stage, decides whether to allow or reject the request. ## 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: - Open the surface in the canvas and click the Surface element (the blue container) to open its configuration panel. - Select the Issuer from the Issuer dropdown. This assigns the owning issuer to the surface and drives trust-registry injection defaults. - Add a Trust Registry element to the canvas and set the Action to inject or both. Configure the Injection Direction (inbound, outbound, or both). - 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](/products/affinidi-trust-fabric/agent-gateway/how-to-guides.md): Step-by-step guide to connecting a trust registry via OOB invitation and assigning it to a surface. - [Enable agent identity on a surface](/products/affinidi-trust-fabric/agent-gateway/how-to-guides.md): Configure inbound identity that trust registries can verify. - [Trust registry reference](/products/affinidi-trust-fabric/agent-gateway/reference/trust-registries/trust-registry.md): Complete field definitions for the trust registry object. - [Agent identity and DIDs](/products/affinidi-trust-fabric/agent-gateway/concepts/identity.md): How agent DIDs are assigned and verified.