Managing Connections

In order for two agents to communicate, they must first be connected. A connection establishes a digital relationship between two agents through which secure issuance, verification, or basic message passing can occur.

Connecting agents

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

  1. One agent creates a connection offer.
  2. The other agent accepts the connection offer.

In order to connect user1 and issuer1, issuer1 creates a connection offer as follows:

curl -u issuer1:issuer1pw -X POST -d '{}' $URL/api/v1/connections -o offer.json -H "Content-Type: application/json"

The offer (i.e. the body of the response from the previous command) is stored in the file offer.json.

And user1 accepts the connection offer as follows:

curl -u user1:user1pw -X POST -d @offer.json $URL/api/v1/connections -H "Content-Type: application/json"

Note that it doesn't matter who creates the offer and who accepts.

In order to connect user1 and verifier1, user1 creates a connection offer as follows:

curl -u user1:user1pw -X POST -d '{}' $URL/api/v1/connections -o offer.json -H "Content-Type: application/json"

And verifier1 accepts the connection offer as follows:

curl -u verifier1:verifier1pw -X POST -d @offer.json $URL/api/v1/connections -H "Content-Type: application/json"

Listing connections

The following command lists the connections for user1.

curl -u user1:user1pw $URL/api/v1/connections

At this point in the tutorial, user1 should be connected to both issuer1 and verifier1; therefore, there should be two connections.

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

curl -u issuer1:issuer1pw $URL/api/v1/connections?remote.name=user1

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": "TRUST_ANCHOR",
        "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:issuer1pw $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, and local.pairwise.did for equality. Any of these DIDs will uniquely identify a connection.

curl -u issuer1:issuer1pw $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:user1pw -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.