# 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

<mark style="color:green;">`GET`</mark> `/api/v1/p2p`

\<Description of the endpoint>

**Headers**

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

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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"
        }
    ]
}
```

{% endtab %}

{% tab title="401" %}

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

{% endtab %}
{% endtabs %}

## Retrieve a specific connection maintained for Alice and Bob

<mark style="color:green;">`GET`</mark> `/api/v1/p2p/{id_connection}`

\<Description of the endpoit>

**Headers**

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

**Body**

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="401" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `/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**

{% tabs %}
{% tab title="201" %}

```json
 "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"
    }
```

{% endtab %}

{% tab title="401" %}

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

{% endtab %}
{% endtabs %}

## Accept a specific connection invitation

<mark style="color:green;">`POST`</mark> `/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**

{% tabs %}
{% tab title="201" %}

```json
{
  "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"
    }
}
```

{% endtab %}

{% tab title="401" %}

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

{% endtab %}
{% endtabs %}

## Creates a communication between two peers in custodial mode

<mark style="color:green;">`POST`</mark> `/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**

{% tabs %}
{% tab title="201" %}

```json
{
    "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
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  
}
```

{% endtab %}
{% endtabs %}