Managing Connections

In order to establish long-term communication between two agents, they must first be connected. A connection establishes a digital relationship between two agents through which secure issuance, verification, or other types of communication may occur.

Connecting agents

There are two or three steps involved in creating a connection between two agents:

  1. One agent, the inviter, creates a connection invitation;
  2. The other agent, the invitee, accepts the connection invitation.
  3. Depending on how the connection invitation was created, the inviter may need to accept the connection offer.

When an agent creates a connection invitation, any of the following optional arguments may be passed in the body of the POST.

Argument Default Value Description
goal None A human-readable description for the purpose or goal of the invitation
goal_code None A machine-readable code indicating the goal of the connection invitation
manual_accept false If true, the inviter must manually accept all connection offers received via this invitation; otherwise, the inviter's agent will automatically accept any such connection offer.
max_acceptances -1 If >= 0, this is the maximum number of times that this invitation may be accepted; otherwise, there is no limit. An invitation can be deleted at any time to prevent any future acceptances from being possible.
direct_route true If true, messages are sent directly to the inviter; otherwise, messages destined for the inviter are proxied through the agency in order to thrwart attempts to gather information through traffic analysis.
properties {} Properties which are set on the connection and associated with the inviter. Properties provided by the inviter when manually accepting a connection offer are also set on the connection and associated with the inviter. If a property is in both the invitation and a manual acceptance property, the value of the manual acceptance property takes precedence.

Either agent can be the inviter, but in order to demonstrate that a single invitation can be accepted by multiple invitees, let user1 be the invitee in order to establish a connection to both issuer1 and verifier1.

User1 creates an invitation as follows. Note that the body of the request is empty, which means all of the default values specified above are used.

curl -u $USER1 -X POST -d '{}' $URL/api/v1/invitations -H "Content-Type: application/json"

The body of the response contains a short_url field which is passed out-of-band to issuer1 and verifier1 and is referred to as below.

Issuer1 accepts the invitation as follows:

curl -u $ISSUER1 -X POST -d '{"url":"<short-invitation-url>"}' $URL/api/v1/connections -H "Content-Type: application/json"

User1 is now connected to issuer1.

Verifier1 accepts the invitation as follows:

curl -u $VERIFIER1 -X POST -d '{"url":"<short-invitation-url>"}' $URL/api/v1/connections -H "Content-Type: application/json"

User1 is now connected to verifier1.

Listing connections

The following command lists the connections for user1.

curl -u $USER1 $URL/api/v1/connections

At this point in the tutorial, user1 should be connected to both issuer1 and verifier1.

Or the following command checks with the issuer1 agent to see if it has a connection with the user1 agent:

curl -u $ISSUER1 $URL/api/v1/connections?

The response will be similar to the following:

  "count": 1,
  "items": [
      "id": "1536854360917",
      "local": {
        "name": "issuer1",
        "pairwise": {
          "did": "5DCSn7LD1oF6cu11usbq3o",
          "verkey": "3J6ZQEGMs4GymNmn7qunbdMbeLoUZqwa7FWpxHtScpru"
        "public": {
          "did": "SeMayuevSNmwrdqPSRNWvi",
          "verkey": "EyfDqyzRXBBgbpvcrqeM72iWRke4tLaUEuf9VYm8NRbU"
        "role": "ENDORSER",
        "url": "https://issuer1:@ab69fe06168c:8443"
      "properties": {},
      "remote": {
        "name": "user1",
        "pairwise": {
          "did": "NBxXpZSBpkmFeMJHYfhGdC",
          "verkey": "CYpmWNYazo3CDqHGHuXFksVnUD6HUVqTELnv6bXJWx1X"
        "public": {
          "did": "UyDsch1V7euY6r7Ba1kXCg",
          "verkey": "GFAdkZ34HxSB5tL5eZvKDnSFnrSKZAGUzHTXVTVD3H1g"
        "role": "NONE",
        "url": "https://user1:@ab69fe06168c:8443"
      "role": "offerer",
      "state": "connected"

You can also check for connectivity by DID rather than by name. For example, the following command returns the same entry because UyDsch1V7euY6r7Ba1kXCg is the remote.public.did from the example above.

curl -u $ISSUER1 $URL/api/v1/connections?remote.public.did=UyDsch1V7euY6r7Ba1kXCg

Or you can use the did query parameter as follows to check remote.public.did, remote.pairwise.did, or local.pairwise.did for equality. Any of these DIDs will uniquely identify a connection.

curl -u $ISSUER1 $URL/api/v1/connections?did=UyDsch1V7euY6r7Ba1kXCg

Deleting Connections

Suppose that user1 wants to delete one of its connections.

Let the connection id for the relationship between user1 and verifier1 be 123456789. In general, the connection id is the value of the id field for a specific connection found when listing connections.

The following would delete the connection from the perspective of both user1 and verifier1; however, do not delete the connection now since you will need it later in the tutorial.

curl -u $USER1 -X DELETE $URL/api/v1/connections/123456789

When user1 deletes the connection, it is logically equivalent to user1 saying: "I no longer want a relationship with verifier1". This means that not only does user1 no longer have a relationship with verifier1, but verifier1 also no longer has a relationship with user1.

Next, let's issue a credential.