Connections

Connections are a representation of an end-to-end encrypted channel between two parties. It's sometimes compared to a "private VPN between two parties." These relationships are designed to be persistent (beyond one-time use) and secure. Connections leverage peer Decentralized Identifiers (peer DIDs) with the following characteristics:

Pairwise - two parties exchange identifiers directly with each other, not with a third party
Pseudonymous - each party generates a new identifier for each connection it makes, improving privacy and non-correlation
Off-ledger - the DIDs are managed in each party's wallet, not on a blockchain

When two parties exchange DIDs, the DID acts as a public key for purposes of encryption. Each party holds a private key associated with the DID that enables them to decrypt messages. Sending secure messages encrypted using DIDs is referred to as DIDComm.

What is the Purpose?

Because connections utilize unique pairwise keys that are used only for communication between the two parties, they enable secure message exchange without fear of man-in-the-middle or other attacks. Because they're persistent, each party knows how to find one another. And since the identifiers and keys are decentralized and managed in the other party's digital wallet, no third-party can take them away.

The best use case for connections is to ensure that subsequent messages are received by the same party that you sent the initial connection invitation to. For example when a connection is made between an Organization and an individual's mobile Wallet, connections enable messages (including credentials and verifications) to be delivered to the individual's device via push notification.

How are connections represented within Trinsic?

To get started with connections, you'll need to:

Create a connection invitation: This is the first step in exchanging DIDs and establishing a connection. The invitation can be found in the invitation field of the API response. A shortened invitationUrl field is also supplied.
Send the invitation to the party you'd like to connect with: This is often done by encoding the invitationUrl field in the API response body into a QR code (see our QR code guide for more details). The invitationUrl can also be opened from a mobile device, which will launch the Trinsic Wallet. The party you'd like to connect with can either accept or reject your invitation. If they reject your invitation, the connection record will remain in the API under the invited state indefinitely. If they accept, the record will change to state connected.

Once you have a connection made, you can:

View your connections: Using the API, you can list all connections at once (optionally filtering by state) or view a specific connection by supplying the connectionId.
Exchange credentials with your connections: The API includes endpoints for issuing credentials and requesting verifications from connections. You can also respond to proposals sent to you by connections, which initiates a verification request.
Send basic messages to your connections: The API supports basic messages to digital wallets. Trinsic Wallet support coming soon.
Delete connections: You can delete a specified connection by supplying the connectionId to the proper endpoint. The other party to the connection will not be notified when you delete the record. Likewise, you won't be notified if the other party deletes you as a connection.

Create a new Connection Invitation

Use the Studio, or use the POST /connections endpoint directly.

Trinsic Studio Steps:

Select the organization.
Select Connections from the sidebar.
Click the + button to the right of the title.
Click the Generate button.
Scan the QR code or enter an email to send the invitation.

Send a Connection Invite

There are few ways to send connection invitation to users. They can be sent as a URL link, encoded as QR code, or simply sent as JSON data. Each approach depends on what the invitee's agent is capable of. When the invitee is using a mobile agent, the most common approach is either a QR code or deep link URL.

In the Trinsic Studio:

You can send a connection invitation by having someone scan a QR code with their wallet, sending an invitation through email, or copying and sending out the link.

Get Connection Status

Use the Studio, or use the GET /connections endpoint directly.

Trinsic Studio Steps:

Select the organization.
Select Connections from the sidebar.
Find and click on the connection in the list.

Which protocols or standards are used?

Multi-party connection invitations

An organization can create what are called "multi-party connection invitations". To do so, execute one of the options below, or use the POST /connections endpoint directly with the attribute multiparty set to true.

Effectively, these are invitations that multiple users can accept to connect with the organization. The status of this connection will always be invited because more users can accept the invitation. Each time a user does so, a new connection entity (with its own connectionId) is created and added to the organization connections, and a new connection webhook is sent to any registered webhooks.