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.

Parameter	Type	Description	Required
`alias`	`string`	Alias for the connection. This is a local alias, and not shared with the other party.	❌
`label`	`string`	Label for the invitation. Will be shared with the other party.	❌ Defaults to project name
`imageUrl`	`string`	Image URL to be included in the invitation. Some wallets render this image.	❌
`isReusable`	`boolean`	Whether multiple connections can be created using the invitation.	❌ Defaults to `false`
`goal`	`string`	Human readable string that describes the goal for creating the invitation.	❌
`goalCode`	`string`	Machine readable string that describes the goal for creating the invitation. Commonly used values for goalCode are `issue-vc`, `request-proof`, `create-account`, or `p2p-messaging`.	❌
`invitationDid`	`did:web`	Use a specific did for the invitation, allowing the receiver to recognize the did, or reuse an existing connection based on the DID. The connection will still use a 'did:peer' did for the connection, this is only for the invitation.	❌

Output

Parameter	Type	Description	Required
`invitationUrl`	`string`	The invitation as a short URL. `valid for 7 days`	✅
`fullInvitationUrl`	`string`	The invitation encoded as URL.	✅
`outOfBandId`	`string`	The 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.

Parameter	Type	Description	Required
`alias`	`string`	Alias for the connection	❌
`label`	`string`	Label for the invitation. Will be shared with the other party.	❌ Defaults to project name
`imageUrl`	`string`	Image URL to be included in the invitation.	❌
`goal`	`string`	Human readable string that describes the goal for creating the invitation.	❌
`goalCode`	`string`	Machine readable string that describes the goal for creating the invitation. Commonly used values for goalCode are `issue-vc`, `request-proof`, `create-account`, or `p2p-messaging`.	❌
`invitationDid`	`did:web`	Use a specific did for the invitation, allowing the receiver to recognize the did, or reuse an existing connection based on the DID. The connection will still use a 'did:peer' did for the connection, this is only for the invitation.	❌

Output

Parameter	Type	Description	Required
`invitationUrl`	`string`	The invitation as a short URL. `valid for 7 days`	✅
`fullInvitationUrl`	`string`	The invitation encoded as URL.	✅
`outOfBandId`	`string`	The identifier of the out of band record. Once a connection is created this identifier will be associated with the created connection.	✅
`connection`	`DidcommConnection`	The created connection	✅

`DidcommConnection`

Parameter	Type	Description	Required
`connectionId`	`string`	The identifier of the connection.	✅
`status`	`string`	The status of the connection. For completed connections the states will always be one of `completed`, `responseSent` or `responseReceived`.	✅
`createdAt`	`number`	Timestamp at which the connection is created in milliseconds since epoch.	✅
`outOfBandId`	`string`	The identifier of the out of band exchange that created the connection.	✅
`alias`	`string`	Alias for the connection. Matches the `alias` given when creating the connection.	❌
`theirLabel`	`string`	The label of the party you are connecting with.	❌
`theirImageUrl`	`string`	The image Url of the party you are connecting with.	❌
`ourDid`	`string`	The 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`.	❌
`theirDid`	`string`	The 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.

Parameter	Type	Description	Required
`invitationUrl`	`string`	The invitation encoded as URL	✅
`alias`	`string`	Alias for the connection	❌
`label`	`string`	Label for the invitation. Will be shared with the other party.	❌ Defaults to project name
`imageUrl`	`string`	Image URL to be included in the connection request.	❌

Output

Parameter	Type	Description	Required
`connection`	`DidcommConnection`	The 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.

Learn about Paradym Credential Templates

Connections

Create Invitation

Input

Output

Usage

Create Connection

Input

Output

DidcommConnection

Usage

Receive Invitation

Input

Output

Usage

What to do with the invitationUrl?

Encode the invitation URL as a QR code

Send the invitation URL to the user

`DidcommConnection`

What to do with the `invitationUrl`?