Communication

This API suite focuses on managing connections within an Identus agent system, with different authentication keys for different subsystems or access levels. The communication layer is mostly managed via DID Comm v2 (within Identus)

Retrieve a list of connections between Alice and Bob

GET /api/v1/p2p

<Description of the endpoint>

Headers

Name	Value
Content-Type	application/json
Authorization	apikey = {Alice's API key}

Body

Response

200

{
    "data": [
        {
            "connectionId": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "thid": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "label": "p2p initiated by snet123",
            "goal": "p2p connection",
            "role": "Inviter",
            "state": "InvitationGenerated",
            "invitation": {
                "id": "af7a1d39-a969-4b0c-9399-03b42229984a",
                "type": "https://didcomm.org/out-of-band/2.0/invitation",
                "from": "did:peer:2.Ez6LStoRKnFA7kTJo3Acj1AsPmXUzDV9VKULWjCpbeCqbR9vq.Vz6MkvXitkonf2UHRkKoNFUMggHMivkHsXZz2hRHaRKfSXxJi.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
                "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFmN2ExZDM5LWE5NjktNGIwYy05Mzk5LTAzYjQyMjI5OTg0YSIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFN0b1JLbkZBN2tUSm8zQWNqMUFzUG1YVXpEVjlWS1VMV2pDcGJlQ3FiUjl2cS5WejZNa3ZYaXRrb25mMlVIUmtLb05GVU1nZ0hNaXZrSHNYWnoyaFJIYVJLZlNYeEppLlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
            },
            "createdAt": "2024-10-03T12:40:35.835452Z",
            "metaRetries": 5,
            "self": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "kind": "Connection"
        },
        {
            "connectionId": "add6d381-1180-484c-bc40-178d362346c0",
            "thid": "add6d381-1180-484c-bc40-178d362346c0",
            "label": "p2p initiated by snet for ping",
            "goal": "p2p connection",
            "myDid": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "theirDid": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "role": "Inviter",
            "state": "ConnectionResponseSent",
            "invitation": {
                "id": "add6d381-1180-484c-bc40-178d362346c0",
                "type": "https://didcomm.org/out-of-band/2.0/invitation",
                "from": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
                "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFkZDZkMzgxLTExODAtNDg0Yy1iYzQwLTE3OGQzNjIzNDZjMCIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFNxcEZVSjV2VzZZVzJENjdxWmlYTnlidmQ3RDJ2cUhUQXZCNEhVakxkQU5vYi5WejZNa3VQY1QxVnZYUGhyQm1NUkpLell3NjZrZ3JCUWRDaUQxTEIxV2JGdkw3Z3g3LlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
            },
            "createdAt": "2024-10-03T12:44:15.81145Z",
            "updatedAt": "2024-10-03T12:44:20.293958Z",
            "metaRetries": 5,
            "self": "add6d381-1180-484c-bc40-178d362346c0",
            "kind": "Connection"
        }
    ]
}

401

{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}

Retrieve a specific connection maintained for Alice and Bob

GET /api/v1/p2p/{id_connection}

<Description of the endpoit>

Headers

Name	Value
Content-Type	application/json
Authorization	apikey = {Alice's API key}

Body

Response

200

{
    "data": {
        "connectionId": "add6d381-1180-484c-bc40-178d362346c0",
        "thid": "add6d381-1180-484c-bc40-178d362346c0",
        "label": "p2p initiated by snet for ping",
        "goal": "p2p connection",
        "myDid": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "theirDid": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "role": "Inviter",
        "state": "ConnectionResponseSent",
        "invitation": {
            "id": "add6d381-1180-484c-bc40-178d362346c0",
            "type": "https://didcomm.org/out-of-band/2.0/invitation",
            "from": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFkZDZkMzgxLTExODAtNDg0Yy1iYzQwLTE3OGQzNjIzNDZjMCIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFNxcEZVSjV2VzZZVzJENjdxWmlYTnlidmQ3RDJ2cUhUQXZCNEhVakxkQU5vYi5WejZNa3VQY1QxVnZYUGhyQm1NUkpLell3NjZrZ3JCUWRDaUQxTEIxV2JGdkw3Z3g3LlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
        },
        "createdAt": "2024-10-03T12:44:15.81145Z",
        "updatedAt": "2024-10-03T12:44:20.293958Z",
        "metaRetries": 5,
        "self": "add6d381-1180-484c-bc40-178d362346c0",
        "kind": "Connection"
    }
}

401

{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}

Create a connection invitation, handling out-of-band invitations

POST /api/v1/p2p/invite

<Description of the endpoint>

Headers

Name	Value
Content-Type	application/json
Authorization	apikey = {Alice's API key}

Body

Name	Type	Description
from	string	This is to generate a nicely formed message

Response

201

 "data": {
        "connectionId": "af7a1d39-a969-4b0c-9399-03b42229984a",
        "thid": "af7a1d39-a969-4b0c-9399-03b42229984a",
        "label": "p2p initiated by snet123",
        "goal": "p2p connection",
        "role": "Inviter",
        "state": "InvitationGenerated",
        "invitation": {
            "id": "af7a1d39-a969-4b0c-9399-03b42229984a",
            "type": "https://didcomm.org/out-of-band/2.0/invitation",
            "from": "did:peer:2.Ez6LStoRKnFA7kTJo3Acj1AsPmXUzDV9VKULWjCpbeCqbR9vq.Vz6MkvXitkonf2UHRkKoNFUMggHMivkHsXZz2hRHaRKfSXxJi.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFmN2ExZDM5LWE5NjktNGIwYy05Mzk5LTAzYjQyMjI5OTg0YSIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFN0b1JLbkZBN2tUSm8zQWNqMUFzUG1YVXpEVjlWS1VMV2pDcGJlQ3FiUjl2cS5WejZNa3ZYaXRrb25mMlVIUmtLb05GVU1nZ0hNaXZrSHNYWnoyaFJIYVJLZlNYeEppLlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
        },
        "createdAt": "2024-10-03T12:40:35.835452249Z",
        "metaRetries": 5,
        "self": "af7a1d39-a969-4b0c-9399-03b42229984a",
        "kind": "Connection"
    }

401

{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}

Accept a specific connection invitation

POST /api/v1/p2p/accept

Headers

Name	Value
Content-Type	application/json
Authorization	apikey = {Bob's API key}

Body

Name	Type	Description
invitation	string	The out of band invitation (eg: eyJpZCI6Ij...dfX0)

Response

201

{
  "data":
    {
        "connectionId": "25cbc847-9df9-4d96-926c-20956d7ca5bc",
        "thid": "add6d381-1180-484c-bc40-178d362346c0",
        "goal": "p2p connection",
        "myDid": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "theirDid": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "role": "Invitee",
        "state": "ConnectionResponseReceived",
        "invitation": {
            "id": "add6d381-1180-484c-bc40-178d362346c0",
            "type": "https://didcomm.org/out-of-band/2.0/invitation",
            "from": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
            "invitationUrl": "https://my.domain.com/path?_oob=eyJpZCI6ImFkZDZkMzgxLTExODAtNDg0Yy1iYzQwLTE3OGQzNjIzNDZjMCIsInR5cGUiOiJodHRwczovL2RpZGNvbW0ub3JnL291dC1vZi1iYW5kLzIuMC9pbnZpdGF0aW9uIiwiZnJvbSI6ImRpZDpwZWVyOjIuRXo2TFNxcEZVSjV2VzZZVzJENjdxWmlYTnlidmQ3RDJ2cUhUQXZCNEhVakxkQU5vYi5WejZNa3VQY1QxVnZYUGhyQm1NUkpLell3NjZrZ3JCUWRDaUQxTEIxV2JGdkw3Z3g3LlNleUowSWpvaVpHMGlMQ0p6SWpwN0luVnlhU0k2SW1oMGRIQTZMeTlvYjNOMExtUnZZMnRsY2k1cGJuUmxjbTVoYkRvNE1UQXdMMlJwWkdOdmJXMGlMQ0p5SWpwYlhTd2lZU0k2V3lKa2FXUmpiMjF0TDNZeUlsMTlmUSIsImJvZHkiOnsiZ29hbCI6InAycCBjb25uZWN0aW9uIiwiYWNjZXB0IjpbXX19"
        },
        "createdAt": "2024-10-03T12:44:17.529663Z",
        "updatedAt": "2024-10-03T12:44:20.284989Z",
        "metaRetries": 5,
        "self": "25cbc847-9df9-4d96-926c-20956d7ca5bc",
        "kind": "Connection"
    }
}

401

{
    "data": null,
    "status": 401,
    "message": "Invalid key"
}

Creates a communication between two peers in custodial mode

POST /api/v1/p2p/custodial/connect

Creates a connection between two peers, in a custodial mode, where the owner (generally peer1) can then act as issuer, verifier, etc...

Headers

Name	Value
Content-Type	application/json
Authorization	None

Body

Name	Type	Description
key_peer1	string	the private authentication key of peer1
key_peer2	string	the private authentication key of peer1
name_peer1	string	name of peer1
name_peer2	string	name of peer2

Response

201

{
    "data": {
        "from": "snet",
        "anonDidFrom": "did:peer:2.Ez6LSqpFUJ5vW6YW2D67qZiXNybvd7D2vqHTAvB4HUjLdANob.Vz6MkuPcT1VvXPhrBmMRJKzYw66kgrBQdCiD1LB1WbFvL7gx7.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "connection_id_from": "add6d381-1180-484c-bc40-178d362346c0",
        "to": "ping",
        "anonDidTo": "did:peer:2.Ez6LSn5R6dTUZzq3eJSA4jnYJjcDM9A96yWQB9SCnMay1pdD2.Vz6Mkik12YQct7UEQeMeC6RTjjBHswsVWTRrq7GSSXPgLutEp.SeyJ0IjoiZG0iLCJzIjp7InVyaSI6Imh0dHA6Ly9ob3N0LmRvY2tlci5pbnRlcm5hbDo4MTAwL2RpZGNvbW0iLCJyIjpbXSwiYSI6WyJkaWRjb21tL3YyIl19fQ",
        "connection_id_to": "25cbc847-9df9-4d96-926c-20956d7ca5bc",
        "thid": "add6d381-1180-484c-bc40-178d362346c0",
        "isAccepted": true
    }
}

401

{
  
}