# Gateways and connection points

> Field reference for gateway records, connection points, and the out-of-band (OOB) approval workflow behind gateway-to-gateway (G2G) DIDComm messaging.

A gateway record represents either this Agent Stream instance (the self gateway) or a remote Trust Fabric appliance it communicates with over DIDComm. A connection point is the inbound DIDComm endpoint one instance exposes so another can reach it. For the conceptual model, see [Trust-fabric integration](/products/affinidi-trust-fabric/agent-stream/concepts/trust-fabric-integration.md).

## Gateway fields

A gateway record is what turns “some other appliance out there” into a named, addressable peer: once it exists, its DID is verified, and its channels are exposed, the rest of Trust Fabric (routing, the marketplace, gateway-level policy) can treat it like any other connected part of the network.

- Exposed Channels left unset exposes every active channel to a connected gateway by default. Scope it down only when a specific remote gateway should see a narrower slice of what you offer.

- A Gateway-Level OPA Policy enforces one rule on everything to or from a specific gateway, regardless of what any individual surface allows. Because a gateway-level deny can’t be overridden by a surface-level allow, it’s the right tool when the boundary you care about is the connection itself, not any one surface.

| Field | Default | Description |
| Gateway Id | Generated automatically | Unique identifier for the gateway record. Used in fabric://{gateway_id}/{channel_id} addressing. Shown as Gateway Id on the gateway edit form. |
| Name | Not set | Display name. |
| Description | Not set | Free-text description. |
| Gateway DID | Not set | The Decentralized Identifier of the remote (or self) appliance. Shown as Gateway DID on the gateway edit form. |
| Type | Remote | Marks whether this is the local appliance (self) or a remote peer; only one self gateway exists per appliance. Never user-selectable — always server-determined. Shown as a LOCAL / REMOTE badge on the Gateways list. |
| Status | Active | Lifecycle state of the gateway (see [Gateway status values](#gateway-status-values)). Shown as the Status column on the Gateways list. The edit form itself only exposes an active/disabled toggle labeled Gateway Enabled; the other states are system-managed and can’t be set directly. |
| Created / Last Updated | Set automatically | Record timestamps. Shown as Created / Last Updated on the gateway edit form, and as Created / Updated columns on the Gateways list. |
| Exposed Channels | None selected (exposes every active channel) | Channel config IDs exposed to this remote gateway. Configured on the gateway edit form’s Exposed Channels Configuration panel (Publishing tab). |
| Gateway-Level OPA Policy | None | Gateway-level OPA policy. For the self gateway it is enforced on all inbound traffic; for a remote gateway it is enforced on outbound traffic to that gateway. A gateway-level deny cannot be overridden by a surface-level allow. Shown under the Gateway-Level OPA Policy heading on the gateway edit form’s Global Policy tab. |

### Gateway status values

| Status | Meaning |
| ACTIVE | Connected and usable (default). |
| PENDING | Gateway record created, connection not yet established. |
| AWAITING APPROVAL | An inbound OOB handshake is waiting on an administrator to call the approval endpoint before it becomes active. |
| DISABLED | Manually disabled. |
| FAILED | The connection attempt or handshake failed. |

### Gateway-level OPA policy fields

| Field | Default | Description |
| Enabled | Off | Whether the gateway-level policy is evaluated. |
| Policy Definition ID | None | ID of the primary reusable policy definition this gateway enforces. The Rego is resolved from the definition at compile time, never copied onto the gateway. Surfaced together with the additional policy definition IDs as a single Select Trust Fabric Policies checklist on the gateway edit form. The UI doesn’t distinguish a “primary” ID separately. |
| Policy Definition IDs | None | Additional reusable policy definitions, evaluated together with the primary one under deny-overrides. Same Select Trust Fabric Policies checklist as above. |

## Connection point fields

A connection point is the inbound DIDComm endpoint one Agent Stream instance exposes for another appliance to reach it, distinct from an Access Point, which is the inbound endpoint callers use to reach a managed agent.

- DID Method defaults to Web, and that’s the right choice for most connection points; reach for WebVH (where available) or Peer only when your network topology specifically calls for it.

- Set an Expires value on an invitation handed to a party you don’t fully control yet. An unused invitation that never expires is a standing door left open.

- Integrations (email, Slack, etc.) notify you as soon as a connection point is used, sparing you the trouble of checking the dashboard for new connections.

| Field | Default | Description |
| Connection Point ID | Generated automatically | Unique identifier for the connection point. Shown as Connection Point ID on the connection point’s Metadata tab. |
| Gateway ID | Not set | Gateway this connection point belongs to. Shown as Gateway ID on the Metadata tab. |
| Mediator ID | Not set | Mediator used to relay DIDComm messages for this connection point. Shown as Mediator ID on the Metadata tab. |
| Connection Point Name / Description | Not set | Operator-facing label and purpose. Shown as Connection Point Name / Description on the Overview tab. |
| Connection Point Link | Not set | The invitation URL for this connection point. Shown as Connection Point Link on the Overview tab. |
| Use Count | 0 | Number of times the invitation has been consumed. Shown as a “N Uses” badge on the connection point’s own Overview tab, not on the Gateways list. |
| Expires | Required, defaults to 24 hours from creation | Invitation expiry. The creation form requires a value (pre-filled 24 hours out, and submission is blocked if cleared); a connection point created some other way (e.g. system-created during a handshake) may carry no expiry at all. Shown as Expiry Date & Time on the creation form; on the Metadata tab the Expires row is shown only when an expiry is set, and omitted entirely otherwise (it never displays “Never”). Also shown as an Expires column on the Gateways list. |
| Created | Set automatically | Shown as Created on the Metadata tab and as a Created column on the Gateways list. |
| Last Updated | Set automatically | The record’s last-modified timestamp. Shown as Last Updated on the Metadata tab — a different field from Last Used below. |
| Last Used | Set automatically once the invitation is consumed | Shown as Last Used on the Overview tab and as a Last used column on the Gateways list. Not shown on the Metadata tab. |
| Integrations | None | Integrations (email, Slack, etc.) triggered off this connection point. Configured on the connection point edit form’s Integrations tab; individual entries are added via a Select Integration dropdown. |
| Creation Type | User | How the connection point was created (see [Connection point creation type](#connection-point-creation-type)). Not a labeled field on the edit page itself — a system-created connection point is marked only with a SYSTEM badge next to its name there, and user-created ones show no badge. The full taxonomy (User-Created, OOB Inviter, OOB Responder, OOB Acceptor, System) is shown as a labeled Type column on the Tasks page instead. |
| Connection Secret | Set when created | Shared secret required to accept the OOB invitation; only an acceptor that knows it can complete the handshake. Shown as Connection Secret in both the creation wizard and the Overview tab. |
| Connection Point Enabled | On | Disabled connection points do not start a WebSocket listener. Shown as the Connection Point Enabled checkbox on the Overview tab. |
| DID Method | Web | DID method used to generate the connection point’s identity: Web, WebVH, or Peer, always available regardless of appliance build. Shown as DID Method on both the creation wizard and the Overview tab. |
| Runtime Status | Not available until the connection is first used | Live health/diagnostics for the connection point’s DIDComm link, written by the listener supervision loop. See [Connection health](#connection-health). |

### Connection point creation type

| Value | Meaning |
| User-Created | Created directly by an operator through the dashboard. |
| OOB Inviter | The permanent connection point created after this instance’s OOB invitation completes. |
| OOB Responder | Auto-created (inviter side) to receive messages back from the acceptor while the handshake is in progress. |
| OOB Acceptor | Auto-created (acceptor side) as the listener endpoint for messages from the inviter. |
| System | Legacy alias, kept for backward compatibility. |

## OOB connection and approval workflow

Connecting two appliances runs an out-of-band (OOB) DIDComm handshake, tracked through two related internal records:

- The low-level handshake record: tracks the temporary and secure DIDs each side presents (the peer’s are set once received), which mediator and connection point are in use, the invitation ID, a role (inviter or acceptor), and a state that moves from waiting-for-response to ready-to-finalize, or to failed. Each entry carries a creation and expiry timestamp and is swept once expired.

- The approval record: the human-in-the-loop approval record for an inbound handshake, whose state moves from awaiting-approval to waiting-for-response to ready-to-finalize, or to failed. A record with an expiry set becomes unusable once expired (approving it then returns 410 Gone); legacy records without an expiry never expire.

Approving a gateway (awaiting-approval → active) is what grants a remote appliance ongoing access to the surfaces and channels you expose. It’s the moment a stranger becomes a trusted peer, so treat it with the same care as handing out a credential. It does the following, in order:

- Verifies the gateway is actually awaiting approval.

- Enforces the appliance’s connection-points limit (see [Settings](/products/affinidi-trust-fabric/agent-stream/reference/configuration/settings.md)).

- Sets the gateway’s name/description from the approval request and its status to active.

- Creates a new connection point using the same mediator as the original OOB invitation.

- Starts that connection point’s WebSocket listener and waits for it to authenticate.

- Sends a DIDComm message accepting the connection, carrying the new connection point’s DID.

The original temporary connection point is deliberately not cleaned up immediately: the acceptor still needs it to resolve and decrypt that message.

- Before clicking Approve Connection, confirm the gateway’s DID and name actually match a source you’ve independently verified out-of-band (a shared invitation link, a phone call, a separate secure channel), rather than approving solely because a request is waiting.

- Once approved, remember the remote appliance can address every surface and channel this gateway exposes, so approve only connections you’d be comfortable granting that reach to.

## Connection health

Each connection point’s DIDComm link is continuously supervised and classified as Connected, Reconnecting, or Failed. The Tasks page lists every connection point with its live status badge alongside a Reconnect Attempts count; the underlying failure reason and retry-schedule timing behind that classification are not broken out into their own columns.

## Addressing with fabric://

Gateway-to-gateway (G2G) calls are addressed as fabric://{gateway_id}/{channel_id}, where gateway_id is a connected gateway’s id and channel_id is the target channel/surface on that remote appliance (for example marketplace-catalog or marketplace-purchase). Resolving one of these addresses finds the gateway’s active WebSocket listener, wraps the HTTP method, path, headers, and body into a DIDComm forwarding message, and waits (30-second timeout) for the matching response. A boundary check rejects any request whose target scheme is not http(s):// or the embedded://marketplace sentinel before it reaches this path, so a stray fabric:// value is never dialed directly over HTTP.

## Related

- [Trust-fabric integration](/products/affinidi-trust-fabric/agent-stream/concepts/trust-fabric-integration.md): The conceptual model for G2G messaging, connection points, and mediators.

- [Payments and marketplace](/products/affinidi-trust-fabric/agent-stream/reference/trust-fabric/payments-and-marketplace.md): How connected gateways’ models appear in an aggregated marketplace catalog.

- [Settings](/products/affinidi-trust-fabric/agent-stream/reference/configuration/settings.md): The appliance limits that gate creating new connection points.

- [Security and access control](/products/affinidi-trust-fabric/agent-stream/concepts/security-and-access-control.md): The RBAC permissions for gateways, connection points, and mediators that gate this page’s records.