Connections

Connections

A connection is needed between the issuer and holder, or holder and verifier that want to exchange credentials or presentations. The way a connection is created is by one party inviting the other and the other accepting the invitation. Under the hood this creates a secure and encrypted communication channel between the two parties.

⚠️

When creating a connection with the Paradym Wallet using the didcomm/createInvitation or didcomm/createConnection actions, the action must be followed up by the didcomm/issueCredential or didcomm/requestPresentation action.

Creating a connection without issuing a credential or requesting a presentation afterwards is not supported by the Paradym Wallet.

If the connection that is created in a workflow execution should be used in the future outside of this workflow execution, the connection ID should be stored outside of Paradym, linked to e.g. an user in your database. The connection ID can be extracted from an execution.

Create Invitation

Name: didcomm/createInvitation
Description: Create a connection invitation, encoded as URL.
Version: v1

This action outputs an invitationUrl that must be used to create a connection. See what to do with the invitationUrl.

With this action, the invitationUrl can be accessed within the workflow, as it does not wait for the connection to be completed before continuing. If you want the workflow execution to wait until the connection has been completed before continuing, use the connections/createConnection action instead.

For example you could use the didcomm/createInvitation action to create an invitation, and then use the general/fetch action to make an API call to send the invitation to your server for further processing.

Create and send invitation
actions:
  - id: createInvitation
    name: didcomm/createInvitation@v1
 
  - id: makeApiCall
    name: general/fetch@v1
    attributes:
      method: 'POST'
      url: https://<your-site.com>/new-invitation
      headers:
        x-api-header: any-value
      payload:
        invitationUrl: $.actions.createInvitation.output.invitationUrl

In the future Paradym will support sending the invitation directly using e.g. Email, SMS or other channels. For now, in most cases you want to use the connections/createConnection action instead, as that waits for the connection to complete before continuing the execution.

Input

The attributes key takes the following input.

ParameterTypeDescriptionRequired
aliasstringAlias for the connection. This is a local alias, and not shared with the other party.
labelstringLabel for the invitation. Will be shared with the other party.

Defaults to project name
imageUrlstringImage URL to be included in the invitation. Some wallets render this image.
isReusablebooleanWhether multiple connections can be created using the invitation.

Defaults to false

Output

ParameterTypeDescriptionRequired
invitationUrlstringThe invitation as a short URL. valid for 7 days
fullInvitationUrlstringThe invitation encoded as URL.
outOfBandIdstringThe identifier of the out of band record. Once a connection is created this identifier will be associated with the created connection.

Usage

YAML
actions:
  - id: createInvitation
    name: didcomm/createInvitation@v1
    attributes:
      alias: 'Alice'

Create Connection

Name: didcomm/createConnection
Description: Create a connection invitation, encoded as URL and wait for the connection to be completed. Can only be used for single use invitations.
Version: v1

This action outputs an invitationUrl that must be used to create a connection. Until this connection is made, the workflow will enter an "on hold" state. See what to do with the invitationUrl.

If you want to use the invitationUrl from within a workflow, the connections/createInvitation action should be used instead.

The most common way to use the invitationUrl is by extracting it from the execution after you've received a workflowExecution.waitingForTrigger webhook notification for the create connection action. See the Issue an Employe Badge example workflow, for a detailed example on how to do this.

Input

The attributes key takes the following input.

ParameterTypeDescriptionRequired
aliasstringAlias for the connection
labelstringLabel for the invitation. Will be shared with the other party.

Defaults to project name
imageUrlstringImage URL to be included in the invitation.

Output

ParameterTypeDescriptionRequired
invitationUrlstringThe invitation as a short URL. valid for 7 days
fullInvitationUrlstringThe invitation encoded as URL.
outOfBandIdstringThe identifier of the out of band record. Once a connection is created this identifier will be associated with the created connection.
connectionDidcommConnectionThe created connection

DidcommConnection

ParameterTypeDescriptionRequired
connectionIdstringThe identifier of the connection.
statusstringThe status of the connection. For completed connections the states will always be one of completed, responseSent or responseReceived.
createdAtnumberTimestamp at which the connection is created in milliseconds since epoch.
outOfBandIdstringThe identifier of the out of band exchange.
aliasstringAlias for the connection. Matches the alias given when creating the connection.
theirLabelstringThe label of the party you are connecting with.
theirImageUrlstringThe image Url of the party you are connecting with.
ourDidstringThe DID (opens in a new tab) used by Paradym to send and receive messages over this DIDComm connection. Will be defined if the connection is ready to be used, and thus has status completed, responseSent or responseReceived.
theirDidstringThe DID (opens in a new tab) used by the other party to send and receive messages over this DIDComm connection. Will be defined if the connection is ready to be used, and thus has status completed, responseSent or responseReceived.

Usage

YAML
actions:
  - id: createConnection
    name: didcomm/createConnection@v1
    attributes:
      alias: 'Alice'

Receive Invitation

Name: didcomm/receiveInvitation
Description: Receive a connection invitation, encoded as URL. Version: v1

Input

The attributes key takes the following input.

ParameterTypeDescriptionRequired
invitationUrlstringThe invitation encoded as URL
aliasstringAlias for the connection
labelstringLabel for the invitation. Will be shared with the other party.

Defaults to project name
imageUrlstringImage URL to be included in the connection request.

Output

ParameterTypeDescriptionRequired
connectionDidcommConnectionThe created connection

Usage

YAML
actions:
  - id: receiveInvitation
    name: didcomm/receiveInvitation@v1
    attributes:
      invitationUrl: 'https://example.com/ssi?c_i=eyXXX'
      alias: 'Alice'

What to do with the invitationUrl?

The invitationUrl must be used by a Holder Wallet to create a connection.

Generally there's two methods to do this:

  • Encode the invitation URL as a QR code. The user can then scan the QR code with their wallet to create the connection.
  • Send the invitation URL to the user, and let them open it by clicking on a link (or a button that opens the link).

Encode the invitation URL as a QR code

In the first case, all you need to do is to encode the invitation URL as a QR code. There's libraries availalbe online to do this, as well as online services. Make sure you trust the service you use, as the invitation URL allows to create a connection with Paradym.

Send the invitation URL to the user

In the second case, you will send the invitation URL to the user, without using a QR code. This can be done by e.g. sending an email containing a link to the invitation URL, on which the user can click, or it can be embedded on a web page.

To make sure the link opens the wallet, the link prefix must be updated to be didcomm:// rather than https://agent.paradym.id/didcomm. This scheme is used by the Paradym Wallet and other wallets to open the invitation URL directly in the wallet. For example, if the invitation URL is https://agent.paradym.id/didcomm?oob=eyXXX, the link must be updated to didcomm://?oob=eyXXX.

In the near future, the Paradym Wallet will support opening the invitation URL directly when clicked on. This means that any user that has the Paradym Wallet will be able to open the invitation URL directly. If the user does not have the Paradym Wallet installed, the user will be shown a page on the Paradym website to download the wallet.

For now, the approach using the didcomm:// prefix should be followed as a workaround.