Managing connections

Edit online

To establish long-term communication between two agents, they must first be connected. A connection establishes a digital relationship between the agents, allowing for secure issuance, verification, or other types of communication.

In this example, the users are referred to as user1 and issuer1.

Note: Each user must obtain an access token to authenticate their respective agents, as the authentication context identifies which agent is performing the operation.

Connecting agents

To connect agents:

The inviting agent (inviter) creates a connection invitation.
The receiving agent (invitee) accepts the invitation.
Depending on how the invitation was created, the inviter needs to accept the connection offer from the invitee.

Listing connections

After a successful agent connection, both the inviter and the inviter can list their connections. The role (inviter or invitee) is determined by who created and who accepted the connection.

curl --location 'https://${service_url}/v1.0/diagency/connections' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${user1_verifiable_credentials_access_token}'

The response includes the following details:

{
{
    "count": 1,
    "items": [
        {
            "id": "750389a6-41a4-443e-8c01-bb8033e82cc6",
            "invitation": {
                ...
            },
            "role": "inviter",
            "state": "connected",            
            ...,
        }
    ]
}

You can filter the list of connected users by using an optional query string parameter. For example, to filter by the invited user name:

GET https://${service_url}/v1.0/diagency/connections?remote.name=${invited_user}

To check connectivity by DID, use the following command:

GET https://${service_url}/v1.0/diagency/connections?remote.public.did=CRG4orwzg21CmvhErsyyjk

This returns the same entry because CRG4orwzg21CmvhErsyyjk is the remote.public.did from the preceding example.

Alternatively, you can use the did query parameter to check remote.public.did, remote.pairwise.did, or local.pairwise.did for equality. Any of these DIDs identifies a unique connection:

GET https://${service_url}/v1.0/diagency/connections?did=CRG4orwzg21CmvhErsyyjk

Deleting connections

When a user deletes a connection, it is effectively severing the relationship with the other agent. This means that neither the user nor the verifier continue having an ongoing relationship.

To delete a connection, use the id field from the connection listing. For example, to delete a connection with a different connection_id, use the following command:

curl --location 'https://${service_url}/v1.0/diagency/connections/2bca772b-1cab-48d3-91b9-df4083ad8821' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${user1_verifiable_credentials_access_token}'

This action removes the connection for both user1 and verifier1.

Note: Without an active connection between agents, credentials cannot be issued or accepted.