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

string

required

UUID of the organization.

Query parameters

number

Page to retrieve. Defaults to 1.

number

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

string

Free-text search across connection fields.

string

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

string

Sort direction. ASC or DESC (default).

Response

number

200 on success.

string

Human-readable result message.

object

Hide properties

number

Total number of connections matching the query.

boolean

Whether a next page exists.

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>"

const response = await fetch(
  'http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections?pageNumber=1&pageSize=10',
  { headers: { Authorization: 'Bearer <your-jwt-token>' } }
);
const data = await response.json();

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

string

required

UUID of the organization.

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

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.

string

Human-readable label to display to the recipient.

string

Internal alias for this invitation.

string

URL of an image to include in the invitation.

string

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

string

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

boolean

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

string[]

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

boolean

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

boolean

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

boolean

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

string

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

string

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

object

Custom routing configuration for the invitation.

object[]

Additional attachments to include in the OOB invitation message.

object[]

Pre-attached messages to deliver alongside the invitation.

Response

object

Hide properties

string

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

object

The raw DIDComm OOB invitation object.

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 '{}'

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 '{
    "label": "Acme Corp",
    "goal": "Connect with Acme Corp to receive your employee credential",
    "goalCode": "issue-vc",
    "multiUseInvitation": true,
    "autoAcceptConnection": true
  }'

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

string

required

UUID of the organization accepting the invitation.

Request body

string

required

The full OOB invitation URL to accept.

string

Internal alias for the resulting connection.

string

Display label for the resulting connection.

boolean

Automatically complete the connection handshake. Defaults to false.

boolean

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

boolean

Attempt to reuse an existing connection with the same peer.

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

string

required

UUID of the organization accepting the invitation.

Request body

object

required

The DIDComm invitation object.

Show invitation fields

string

Unique identifier for the invitation message.

string

required

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

string

required

Human-readable label for the inviter.

string

Intended goal code.

string

Human-readable goal description.

string[]

Array of supported handshake protocol URIs.

object[]

required

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

string

Optional image URL included in the invitation.

string

Internal alias for the resulting connection.

boolean

Automatically complete the handshake.

boolean

Automatically accept without user confirmation.

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

string

required

UUID of the organization.

string

required

ID of the connection over which to send the question.

Request body

string

required

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

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" }]

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

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

string

required

UUID of the organization.

string

required

UUID of the connection to message.

Request body

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

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.

​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

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