Connections

Connections represent a peer-to-peer relationship using a pairwise key exchange. When two parties establish a connection, they can exchange various data messages securely.

Connections include a set of unique pairwise keys that are only used for communication between the parties involved in the connection relationship. Connections are negotiated with an exchange of messages and start with an invitation message.

In our API, each connection is represened with a connectionId and this identifier is used to reference this connection throughout the different endpoints.

The process of establishing connections is described in Aries RFC 0023: DID Exchange Protocol 1.0

Creating new connection (invitation)

To create a new invitation, call the POST /connections endpoint or use the service clients for your platform. Connection invitations can also be created and managed using the Trinsic Studio.

var connectionId = await client.CreateConnectionAsync(new ConnectionInvitationParameters());

API Reference

This uses the POST /connections endpoint, which is documented here in Swaggerhub.

Retrieving connections data

To get the details of a connection (including invitation details), call the GET /connections/{connectionId} endpoint, by passing the connection identifier you obtained as result when creating new connection.

var connectionContract = await client.GetConnectionAsync(connectionId);

API Reference

This uses the GET /connections/{'{connectionId}'} endpoint, which is documented here in Swaggerhub.

Sending invitations to users

There are few ways to send connection invitation to users. They can be sent as a URL link, encoded as QR code, or just JSON. 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.

Encoding invitations as QR code

To encode the invitation as QR code, a certain direction has been accepted by the community. This approach, however, is not strictly standardized. It will work with the Trinsic Wallet.

QR codes should decode into a URL of the format below

[url_scheme]://[host]?c_i=[invitation_data]

Example:

https://example.com/?c_i=...

A quick and simple way to get a QR code is by using Google Chart API. Simply pass your URL to the Google endpoint:

https://chart.googleapis.com/chart?cht=qr&chl=[INVITATION_URL]&chs=200x200&chld=L|1

When mobile apps scan this code, they will look for the query parameter c_i and use the value of this parameter to decode the Base64 Url encoded string into a Connection Invitation Message. The URL scheme and host can be anything. They are generally used as utility to redirect the user to a friendly page that directs the user to download mobile agents.

URL schemes can also be used as deep linking tool, to launch mobile agents directly from the link. This is useful if you're developing custom agent apps and would like to support connections and invitations in a convenient user experience.

Using invitations with deep links

To prepare an invitation with a custom deep link URL scheme, simply format the URL

my_custom_scheme://launch/?c_i=[INVITATION_DATA]

The invitation data is retreived from your connection record in the field invitation (not invitationUrl).

The Trinsic Wallet uses the following custom deep link URL: id.streetcred://launch?c_i=[INVITATION_DATA]

If you open the invitationUrl from the connection record from a mobile device, it will try to launch our mobile agent app.