DIDComm API

What is DIDComm?

DIDComm (DID Communication) is a messaging protocol where parties communicate using their DIDs. Unlike REST APIs where a client calls a server, DIDComm enables peer-to-peer messaging between any two parties identified by DIDs.

BaseID Cloud provides a DIDComm relay — you can send and receive DIDComm messages through the API, and the platform tracks protocol threads (multi-step conversations like credential issuance).

When to use DIDComm

Use case	DIDComm	REST API
Credential issuance	Offer → Request → Issue (3-step protocol)	Single POST /v1/credentials/issue
Presentation exchange	Request → Present (2-step)	Single POST /v1/verify
Connectivity check	Trust-ping → Ping-response	GET /health
Interop with wallets	Required for Aries/DIDComm wallets	Not supported by DIDComm wallets

Use DIDComm when interoperating with DIDComm-native wallets (Aries, ACA-Py, BC Wallet). Use the REST API for simpler server-to-server integration.

---

Supported protocols

Protocol	Version	Message types
Trust Ping	2.0	ping, ping-response
Issue Credential	3.0	offer-credential, request-credential, issue-credential
Present Proof	3.0	request-presentation, presentation

---

Send a message

Create and send a DIDComm v2 message.

POST /v1/didcomm/send
Authorization: Bearer <token>

Permission required: didcomm:send

Request body

Field	Type	Required	Description
action	string	Yes	Protocol action (see below)
from_did	string	Yes	Sender DID
to_did	string	Yes	Recipient DID
body	object	No	Message body — content depends on the protocol

Actions

Action	Protocol	What it does
trust-ping	Trust Ping 2.0	Send a connectivity check. The recipient should respond with a ping-response.
offer-credential	Issue Credential 3.0	Offer a credential to a holder. Include the credential preview in body.
request-presentation	Present Proof 3.0	Request a verifiable presentation. Include the proof request in body.

Example — trust ping

Test connectivity with another DID:

curl -X POST https://api.baseid.cloud/v1/didcomm/send \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "trust-ping",
    "from_did": "did:key:z6MkSender",
    "to_did": "did:key:z6MkRecipient"
  }'

Example — offer a credential

curl -X POST https://api.baseid.cloud/v1/didcomm/send \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "offer-credential",
    "from_did": "did:key:z6MkIssuer",
    "to_did": "did:key:z6MkHolder",
    "body": {
      "credential_preview": {
        "type": "CanadianDigitalID",
        "claims": {"givenName": "Alice", "province": "Ontario"}
      }
    }
  }'

Response

{
  "message_id": "msg-abc123",
  "thread_id": "msg-abc123",
  "type": "https://didcomm.org/trust-ping/2.0/ping",
  "status": "sent"
}

---

Receive a message

Process an incoming DIDComm message. For trust-ping messages, a response is automatically generated.

POST /v1/didcomm/receive
Authorization: Bearer <token>

Permission required: didcomm:receive

Request body

A full DIDComm v2 Message object:

{
  "id": "msg-xyz",
  "type": "https://didcomm.org/trust-ping/2.0/ping",
  "from": "did:key:z6MkSender",
  "to": ["did:key:z6MkRecipient"],
  "body": { "response_requested": true },
  "created_time": 1711459200
}

Message fields

Field	Type	Description
id	string	Unique message identifier
type	string	Protocol message type URI
from	string	Sender DID
to	string[]	Recipient DID(s)
thid	string	Thread ID — links related messages in a protocol
pthid	string	Parent thread ID — for nested protocols
body	object	Protocol-specific message content
attachments	array	Binary or JSON attachments (credentials, proof requests)
created_time	number	Unix timestamp

Response

{
  "message_id": "msg-xyz",
  "thread_id": "msg-xyz",
  "type": "https://didcomm.org/trust-ping/2.0/ping",
  "status": "received",
  "response": {
    "response_id": "msg-resp-abc",
    "type": "https://didcomm.org/trust-ping/2.0/ping-response"
  }
}

The response field is included when the protocol requires an automatic response (e.g., trust-ping).

---

Thread tracking

DIDComm protocols are multi-step conversations linked by a thread ID. BaseID tracks thread state so you can monitor protocol progress.

List threads

GET /v1/didcomm/threads
Authorization: Bearer <token>

Permission required: didcomm:receive

Get a thread

GET /v1/didcomm/threads/:id
Authorization: Bearer <token>

Response

{
  "id": "msg-abc123",
  "type": "https://didcomm.org/trust-ping/2.0/ping",
  "from": "did:key:z6MkSender",
  "to": ["did:key:z6MkRecipient"],
  "status": "sent",
  "created_at": "2026-03-26T12:00:00Z"
}

Thread lifecycle

1. Send offer-credential     → thread created (status: sent)
2. Receive request-credential → thread updated (status: received)
3. Send issue-credential      → thread updated (status: completed)

---

Attachments

DIDComm messages can include attachments for credentials, proof requests, or other binary data:

{
  "attachments": [
    {
      "id": "att-1",
      "media_type": "application/json",
      "data": {
        "json": { "credential": "eyJ..." }
      }
    }
  ]
}

Attachment data formats

Format	Field	Use case
JSON	{ "json": {...} }	Credential previews, proof requests
Base64	{ "base64": "..." }	Binary data, CBOR-encoded credentials
Links	{ "links": ["https://..."], "hash": "..." }	Large files with integrity check

---

See also

• Protocols concept — DIDComm vs OID4VCI/VP comparison
• DIDs concept — DID-based messaging identities
• Trust API — trust attestations between DIDComm peers