Connections - CREDEBL Platform

A connection represents a DIDComm peer-to-peer channel established between two agents. Once a connection is active, both parties can exchange verifiable credentials, proof requests, and basic messages without disclosing their DIDs to third parties. CREDEBL supports two connection methods:

Invitation-based — one agent creates an invitation object or URL; the peer accepts it to complete the handshake.
Out-of-band (OOB) — an invitation is shared as a URL or QR code and can be scanned by any compatible agent. OOB invitations may be single-use or reusable (multiUseInvitation).

Base path

All endpoints are rooted at /orgs/:orgId/connections or /orgs/:orgId/question-answer.

Authentication

Every endpoint requires a JWT bearer token.

Authorization: Bearer <your-jwt-token>

Role-based access

Role	Allowed operations
`owner`, `admin`, `issuer`, `verifier`, `member`	Read connections, create invitations
`owner`	Delete all connection records
`owner`, `admin`, `issuer`, `verifier`, `member`, `holder`, `super_admin`, `platform_admin`	Send questions and basic messages

Endpoints

List connections

GET /orgs/:orgId/connections — Paginated list of all connections for an organization.

Get connection

GET /orgs/:orgId/connections/:connectionId — Retrieve a single connection by its ID.

Create invitation

POST /orgs/:orgId/connections — Create an outbound OOB connection invitation.

Receive invitation URL

POST /orgs/:orgId/receive-invitation-url — Accept an invitation delivered as a URL.

Receive invitation object

POST /orgs/:orgId/receive-invitation — Accept an invitation delivered as a JSON object.

Send question

POST /orgs/:orgId/question-answer/question/:connectionId — Send a question-and-answer message over a connection.

Get Q&A records

GET /orgs/:orgId/question-answer/question — Retrieve all question-answer records for an organization.

Send basic message

POST /orgs/:orgId/basic-message/:connectionId — Send a plain-text message over a connection.

Delete connections

DELETE /orgs/:orgId/connections — Delete all connection records for an organization.

List connections

GET /orgs/:orgId/connections Retrieve all connections for an organization. Supports pagination, full-text search, and sorting. Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId

string

required

UUID of the organization.

Query parameters

pageNumber

number

Page to retrieve. Defaults to 1.

pageSize

number

Number of records per page. Min 1, max 100. Defaults to 10.

searchByText

string

Free-text search across connection fields.

sortField

string

Field to sort by. Enum: createDateTime (default) and other available sort fields.

sortBy

string

Sort direction. ASC or DESC (default).

Response

statusCode

number

200 on success.

message

string

Human-readable result message.

data

object

Hide properties

totalItems

number

Total number of connections matching the query.

hasNextPage

boolean

Whether a next page exists.

connections

object[]

Array of connection records. Each record includes id, state, theirLabel, did, theirDid, createdAt, updatedAt, and outOfBandId.

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections?pageNumber=1&pageSize=10&sortBy=DESC" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Connections fetched successfully",
  "data": {
    "totalItems": 2,
    "hasNextPage": false,
    "connections": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "state": "completed",
        "theirLabel": "Alice",
        "did": "did:peer:1zQmXyz...",
        "theirDid": "did:peer:1zQmAbc...",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:45.000Z",
        "outOfBandId": "a5cc3c28-db5e-4da4-8d29-37d7ab8b67a1"
      }
    ]
  }
}

Get connection by ID

GET /orgs/:orgId/connections/:connectionId Retrieve the details of a specific connection. Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId

string

required

UUID of the organization.

connectionId

string

required

UUID of the connection to retrieve.

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Connection fetched successfully",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "state": "completed",
    "role": "inviter",
    "did": "did:peer:1zQmXyz...",
    "theirDid": "did:peer:1zQmAbc...",
    "theirLabel": "Alice",
    "autoAcceptConnection": true,
    "protocol": "https://didcomm.org/connections/1.0",
    "outOfBandId": "a5cc3c28-db5e-4da4-8d29-37d7ab8b67a1",
    "threadId": "b0f49aa6-1516-4b21-9190-b13e92c0c865",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:45.000Z"
  }
}

Status	Description
`400 Bad Request`	`connectionId` is not a valid UUID.
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	Authenticated user lacks the required role.

Create connection invitation

POST /orgs/:orgId/connections Creates an outbound out-of-band connection invitation. The response contains an invitation URL and object that the peer can use to establish a connection. Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId

string

required

UUID of the organization creating the invitation.

Request body

All fields are optional. When the body is omitted or left empty, a default invitation is created.

label

string

Human-readable label to display to the recipient.

alias

string

Internal alias for this invitation.

imageUrl

string

URL of an image to include in the invitation.

goalCode

string

A code expressing the intended goal of the connection (e.g., "issue-vc").

goal

string

A human-readable description of the connection’s purpose.

handshake

boolean

Whether to include a handshake protocol in the invitation. Defaults to true.

handshakeProtocols

string[]

Array of DIDComm handshake protocol URIs to advertise. For example, ["https://didcomm.org/connections/1.0"].

multiUseInvitation

boolean

When true, the invitation can be accepted by multiple peers. Defaults to false.

autoAcceptConnection

boolean

Automatically accept the connection once the peer responds. Defaults to false.

IsReuseConnection

boolean

Attempt to reuse an existing connection if one exists with the same peer.

recipientKey

string

A specific recipient key (verkey) to use for this invitation.

invitationDid

string

A DID to use as the invitation endpoint instead of a service endpoint.

routing

object

Custom routing configuration for the invitation.

appendedAttachments

object[]

Additional attachments to include in the OOB invitation message.

messages

object[]

Pre-attached messages to deliver alongside the invitation.

Response

data

object

Hide properties

invitationUrl

string

The full OOB invitation URL. Share this as a QR code or deep link.

invitation

object

The raw DIDComm OOB invitation object.

outOfBandRecord

object

The persisted OOB record created by the agent.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{}'

201 response

{
  "statusCode": 201,
  "message": "Connection invitation created successfully",
  "data": {
    "invitationUrl": "http://agent.example.com?oob=eyJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvb3V0LW9mLWJhbmQvMS4xL2ludml0YXRpb24iLCJAaWQiOiJhNWNjM2MyOC1kYjVlLTRkYTQtOGQyOS0zN2Q3YWI4YjY3YTEiLCJsYWJlbCI6IkFjbWUgQ29ycCIsImhhbmRzaGFrZV9wcm90b2NvbHMiOlsiaHR0cHM6Ly9kaWRjb21tLm9yZy9jb25uZWN0aW9ucy8xLjAiXSwic2VydmljZXMiOlt7ImlkIjoiI2lubGluZSIsInR5cGUiOiJEaWRDb21tTWVzc2FnaW5nIiwicmVjaXBpZW50S2V5cyI6WyJkaWQ6a2V5OnpYeXoiXSwic2VydmljZUVuZHBvaW50IjoiaHR0cDovL2FnZW50LmV4YW1wbGUuY29tIn1dfQ==",
    "invitation": {
      "@type": "https://didcomm.org/out-of-band/1.1/invitation",
      "@id": "a5cc3c28-db5e-4da4-8d29-37d7ab8b67a1",
      "label": "Acme Corp",
      "handshake_protocols": ["https://didcomm.org/connections/1.0"],
      "services": [
        {
          "id": "#inline",
          "type": "did-communication",
          "recipientKeys": ["did:key:zXyz..."],
          "serviceEndpoint": "http://agent.example.com"
        }
      ]
    }
  }
}

Receive invitation URL

POST /orgs/:orgId/receive-invitation-url Accept an OOB invitation delivered as a URL string. The agent parses the URL and completes the connection handshake. Required roles: owner, admin

Path parameters

orgId

string

required

UUID of the organization accepting the invitation.

Request body

invitationUrl

string

required

The full OOB invitation URL to accept.

alias

string

Internal alias for the resulting connection.

label

string

Display label for the resulting connection.

autoAcceptConnection

boolean

Automatically complete the connection handshake. Defaults to false.

autoAcceptInvitation

boolean

Automatically accept the invitation without user confirmation. Defaults to false.

reuseConnection

boolean

Attempt to reuse an existing connection with the same peer.

acceptInvitationTimeoutMs

number

Timeout in milliseconds to wait for the peer to respond.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/receive-invitation-url" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "invitationUrl": "http://agent.example.com?oob=eyJAdHlwZSI6...",
    "autoAcceptConnection": true,
    "autoAcceptInvitation": true
  }'

Receive invitation object

POST /orgs/:orgId/receive-invitation Accept an OOB invitation delivered as a raw JSON invitation object. Required roles: owner, admin

Path parameters

orgId

string

required

UUID of the organization accepting the invitation.

Request body

invitation

object

required

The DIDComm invitation object.

Show invitation fields

@id

string

Unique identifier for the invitation message.

@type

string

required

DIDComm message type URI, for example "https://didcomm.org/out-of-band/1.1/invitation".

label

string

required

Human-readable label for the inviter.

goalCode

string

Intended goal code.

goal

string

Human-readable goal description.

handshake_protocols

string[]

Array of supported handshake protocol URIs.

services

object[]

required

Array of service endpoint objects. Each must include id, type, serviceEndpoint (URL), and recipientKeys (string array).

imageUrl

string

Optional image URL included in the invitation.

alias

string

Internal alias for the resulting connection.

autoAcceptConnection

boolean

Automatically complete the handshake.

autoAcceptInvitation

boolean

Automatically accept without user confirmation.

reuseConnection

boolean

Attempt to reuse an existing connection with the same peer.

Send question

POST /orgs/:orgId/question-answer/question/:connectionId Send a question-and-answer message to a connected peer. The peer receives a list of valid text responses and must pick one. Required roles: owner, admin, issuer, verifier, member, holder, super_admin, platform_admin

Path parameters

orgId

string

required

UUID of the organization.

connectionId

string

required

ID of the connection over which to send the question.

Request body

question

string

required

The question text to send to the peer. Example: "What is your name?".

validResponses

object[]

required

Array of valid response objects the peer may choose from. Each object must have a text (string) field.Example: [{ "text": "Emma" }, { "text": "Kiva" }]

detail

string

Optional supplementary detail or context for the question.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/question-answer/question/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "question": "Which department do you belong to?",
    "detail": "Please select your department for credential issuance.",
    "validResponses": [
      { "text": "Engineering" },
      { "text": "Finance" },
      { "text": "Legal" }
    ]
  }'

201 response

{
  "statusCode": 201,
  "message": "Question sent successfully",
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "state": "question-sent",
    "questionText": "Which department do you belong to?",
    "questionDetail": "Please select your department for credential issuance.",
    "validResponses": [
      { "text": "Engineering" },
      { "text": "Finance" },
      { "text": "Legal" }
    ],
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2024-01-15T11:00:00.000Z"
  }
}

Get question-answer records

GET /orgs/:orgId/question-answer/question Retrieve all question-answer records for the organization. Required roles: owner, admin, issuer, verifier, member, holder, super_admin, platform_admin

Path parameters

orgId

string

required

UUID of the organization.

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/question-answer/question" \
  --header "Authorization: Bearer <your-jwt-token>"

Send basic message

POST /orgs/:orgId/basic-message/:connectionId Send a plain-text DIDComm basic message to a connected peer. Required roles: owner, admin, issuer, verifier, member, holder, super_admin, platform_admin

Path parameters

orgId

string

required

UUID of the organization.

connectionId

string

required

UUID of the connection to message.

Request body

content

string

The plain-text message body to send.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/basic-message/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "content": "Hello! Your credential is ready for collection."
  }'

201 response

{
  "statusCode": 201,
  "message": "Basic message sent successfully",
  "data": {
    "id": "c2e43f80-9f3a-4b12-835d-ecb9e4f12abc",
    "content": "Hello! Your credential is ready for collection.",
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2024-01-15T11:05:00.000Z"
  }
}

Delete connections

DELETE /orgs/:orgId/connections Delete all connection records associated with an organization. This action is irreversible. Required roles: owner

Path parameters

orgId

string

required

UUID of the organization whose connection records will be deleted.

Examples

curl --request DELETE \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Connection records deleted successfully"
}

Status	Description
`400 Bad Request`	`orgId` is not a valid UUID.
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	Authenticated user does not have the `owner` role.

Authentication

Organizations

Connections & Credentials

Ecosystem & Wallet

​Base path

​Authentication

​Role-based access

​Endpoints

List connections

Get connection

Create invitation

Receive invitation URL

Receive invitation object

Send question

Get Q&A records

Send basic message

Delete connections

​List connections

​Path parameters

​Query parameters

​Response

​Examples

​Get connection by ID

​Path parameters

​Examples

​Create connection invitation

​Path parameters

​Request body

​Response

​Examples

​Receive invitation URL

​Path parameters

​Request body

​Examples

​Receive invitation object

​Path parameters

​Request body

​Send question

​Path parameters

​Request body

​Examples

​Get question-answer records

​Path parameters

​Examples

​Send basic message

​Path parameters

​Request body

​Examples

​Delete connections

​Path parameters

​Examples

Build docs developers (and LLMs) love

Base path

Authentication

Role-based access

Endpoints

List connections

Path parameters

Query parameters

Response

Examples

Get connection by ID

Path parameters

Examples

Create connection invitation

Path parameters

Request body

Response

Examples

Receive invitation URL

Path parameters

Request body

Examples

Receive invitation object

Path parameters

Request body

Send question

Path parameters

Request body

Examples

Get question-answer records

Path parameters

Examples

Send basic message

Path parameters

Request body

Examples

Delete connections

Path parameters

Examples