Trinsic

The Trinsic Docs

Welcome to the Trinsic Docs. You'll find comprehensive guides and documentation to help you start working with Trinsic as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Connections

ConnectionConnection - A connection is a peer-to-peer relationship using a pairwise key exchange. It is the most secure way to offer, issue, and verify credential. The process of establishing connections is described in Aries RFC 0023: DID Exchange Protocol 1.0.s 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 IdentifiersDecentralized Identifiers - A kind of identifier that is controlled by its subject (or assigns) and doesn't depend on a centralized registry, identity provider, or certificate authority. Each organization created in the Trinsic platform has a public DID written to the network it's setup on. Connections leverage pairwise, private DIDs to facilitate message exchange. Learn more at the Decentralized Identifiers W3C Spec Abstract. (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 DIDCommDIDComm - DIDComm is the technical protocol used when two agents or wallets communicate. Trinsic's pricing model is based on DIDComm usage; we measure both incoming and outgoing DIDComm messages from any agent we're hosting on your behalf and charge for that usage based on the plan you've subscribed to..

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 OrganizationOrganization - An organization is a Trinsic-hosted agent controlled by a legal entity and provisioned with the capability to engage in credential issuance and verification. It is synonymous with tenant in the Trinsic platform. and an individual's mobile WalletWallet - Software that securely stores credentials. It also stores identifiers, proofs, messages, and other information exchanged between two agents., 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 WalletTrinsic Wallet - The Trinsic Wallet is a cross-platform mobile application that enables individuals to acquire a free generic SSI wallet. It provisions an agent locally on the device and leverages the secure enclave on device for key management. It also provides backup, restore, import, and export functionality. It is available on the App Store and the Google Play Store.. 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:

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

create invitation in dashboard

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 a 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:

  1. Select the organization.
  2. Select Connections from the sidebar.
  3. 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.

Updated 2 months ago


Connections


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.