Credential verification - CREDEBL Platform

Verification allows a verifier organization to request that a holder prove they possess one or more credentials. CREDEBL supports two verification flows:

Connection-based proof request — send a proof request to a holder over an established DIDComm connection.
Out-of-band (OOB) proof request — generate a proof request invitation that a holder can accept without a pre-existing connection. Can also be sent via email.

Two request formats are supported:

Indy (AnonCreds) — request specific attributes and/or predicates from AnonCreds credentials, optionally restricting by credDefId or schemaId.
Presentation Exchange (DIF PE) — request credentials using a W3C Presentation Definition with input_descriptors.

Base path

All endpoints are rooted at /orgs/:orgId/proofs or /orgs/:orgId/verified-proofs.

Authentication

Every endpoint requires a JWT bearer token.

Authorization: Bearer <your-jwt-token>

Role-based access

Operation	Required roles
Send proof requests	`owner`, `admin`, `verifier`
Read proof presentations	`owner`, `admin`, `issuer`, `verifier`, `member`, `holder`
Delete verification records	`owner`

Endpoints

Send proof request

POST /orgs/:orgId/proofs — Request a proof from a connected holder.

Send OOB proof request

POST /orgs/:orgId/proofs/oob — Generate an OOB proof request invitation.

Verify presentation

POST /orgs/:orgId/proofs/:proofId/verify — Verify a submitted proof presentation.

List proof presentations

GET /orgs/:orgId/proofs — Retrieve all proof presentation records.

Get proof presentation

GET /orgs/:orgId/proofs/:proofId — Retrieve a specific proof record.

Get verified proof details

GET /orgs/:orgId/verified-proofs/:proofId — Get the verified attribute values from a completed proof.

Delete verification records

DELETE /orgs/:orgId/verification-records — Delete all verification records for an organization.

Send proof request

POST /orgs/:orgId/proofs Send a proof request to a connected holder. Two API versions are available that differ only in how connectionId is specified. Required roles: owner, admin, verifier

Path parameters

string

required

UUID of the verifier organization.

Query parameters

string

required

Proof request format. Enum: INDY (default) or PRESENTATIONEXCHANGE.

Request body

v1 — single connection
v2 — multiple connections

POST /orgs/:orgId/proofs (unversioned / default)

string

required

UUID of the single connection to send the proof request to.

object

Required when requestType is INDY. Contains an indy sub-object.

Show proofFormats.indy

object[]

required

Array of requested attribute/predicate objects. Each object may include:

attributeName (string) — request a single attribute by name. Mutually exclusive with attributeNames.
attributeNames (string[]) — request multiple attributes in a single group. Mutually exclusive with attributeName.
schemaId (string, optional) — restrict to credentials from this schema.
credDefId (string, optional) — restrict to credentials from this credential definition.
condition (string, optional) — predicate condition operator: >=, <=, >, <. Required when value is set.
value (string, optional) — numeric string for predicate comparison. Required when condition is set.

object

Required when requestType is PRESENTATIONEXCHANGE. A W3C Presentation Definition object.

Show presentationDefinition fields

string

required

Unique identifier for this presentation definition.

string

Human-readable description of the verification purpose.

object[]

required

Array of input descriptor objects, each specifying what credential data is requested. Min 1 element.Each descriptor must include:

id (string, required) — unique descriptor ID.
name (string, optional) — human-readable name.
purpose (string, optional) — reason for requesting this descriptor.
schema (object[], required) — array of schema URIs: [{ "uri": "https://..." }].
constraints (object, optional) — contains fields array, each with a path (string[]) JSONPath.

string

Optional comment attached to the proof request.

string

Automatic proof acceptance mode. Enum: always, contentApproved, never.

string

Goal code for the proof request thread.

string

Attach this proof request to an existing thread.

boolean

Whether the verifier will confirm receipt.

string

DIDComm protocol version.

POST /v2/orgs/:orgId/proofs (API version 2)Identical to v1, except connectionId accepts an array of UUIDs to send the same proof request to multiple connections simultaneously.

string[]

required

Array of connection UUIDs to send the proof request to. Min 1 element. Maximum is controlled by the PROOF_REQ_CONN_LIMIT environment variable.

All other fields (proofFormats, presentationDefinition, comment, autoAcceptProof, etc.) are identical to v1.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs?requestType=INDY" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "comment": "KYC verification for onboarding",
    "autoAcceptProof": "never",
    "proofFormats": {
      "indy": {
        "attributes": [
          {
            "attributeName": "firstName",
            "credDefId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default"
          },
          {
            "attributeName": "lastName",
            "credDefId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default"
          },
          {
            "attributeName": "employeeId",
            "schemaId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0"
          }
        ]
      }
    }
  }'

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs?requestType=INDY" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "proofFormats": {
      "indy": {
        "attributes": [
          {
            "attributeName": "age",
            "condition": ">=",
            "value": "18",
            "schemaId": "WgWxqztrNooG92RXvxSTWv:2:PersonCredential:1.0"
          }
        ]
      }
    }
  }'

curl --request POST \
  --url "http://localhost:5000/v2/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs?requestType=INDY" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "a1b2c3d4-1234-5678-90ab-cdef12345678"
    ],
    "proofFormats": {
      "indy": {
        "attributes": [
          {
            "attributeName": "employeeId",
            "credDefId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default"
          }
        ]
      }
    }
  }'

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs?requestType=PRESENTATIONEXCHANGE" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "presentationDefinition": {
      "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
      "purpose": "Used for KYC verification.",
      "input_descriptors": [
        {
          "id": "employment_input_1",
          "name": "Employment Verification",
          "purpose": "Verify current employment",
          "schema": [
            { "uri": "https://schemas.example.com/employee/1.0" }
          ],
          "constraints": {
            "fields": [
              { "path": ["$.credentialSubject.employeeId"] },
              { "path": ["$.credentialSubject.department"] }
            ]
          }
        }
      ]
    }
  }'

201 response

{
  "statusCode": 201,
  "message": "Proof request sent successfully",
  "data": {
    "id": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "state": "request-sent",
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "threadId": "e1f2g3h4-5678-90ab-cdef-123456789012",
    "protocolVersion": "v1",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

Status	Description
`400 Bad Request`	`requestType` is `INDY` but `proofFormats` is missing; or `requestType` is `PRESENTATIONEXCHANGE` but `presentationDefinition` is missing.
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	User does not have `owner`, `admin`, or `verifier` role.

Send out-of-band proof request

POST /orgs/:orgId/proofs/oob Create an out-of-band proof request invitation. The holder can scan the resulting URL or QR code to respond without a pre-existing connection. The invitation can also be sent to one or more email addresses. Required roles: owner, admin, verifier

Path parameters

string

required

UUID of the verifier organization.

Query parameters

string

required

Proof request format. Enum: INDY (default) or PRESENTATIONEXCHANGE.

Request body

object

Proof format for Indy requests. Contains the indy sub-object with requested_attributes and requested_predicates.

Show proofFormats.indy

string

Human-readable name for the proof request. Example: "Verify national identity".

string

Version string for the proof request. Example: "1.0".

object

A map of referent keys to attribute request objects. Each value may include name (single attribute), names (multi-attribute), and restrictions (array of restriction objects using schema_id, cred_def_id, etc.).

object

A map of referent keys to predicate request objects. Each value must include name, p_type (>=, <=, >, <), and p_value.

object

W3C Presentation Definition. Required when requestType is PRESENTATIONEXCHANGE. Same structure as the connection-based flow.

string

Optional comment.

string

Goal code for the proof request thread.

string

DIDComm protocol version.

string

Automatic proof acceptance mode. Enum: always, contentApproved, never.

boolean

Return a shortened invitation URL. Defaults to true.

string[]

Optional array of email addresses to deliver the proof request invitation to. Each must be a valid email. Max size controlled by OOB_BATCH_SIZE environment variable.

boolean

Attempt to reuse an existing connection with the holder.

string

Optional display label for the OOB invitation.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs/oob?requestType=INDY" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "comment": "Please verify your employment credentials",
    "isShortenUrl": true,
    "proofFormats": {
      "indy": {
        "name": "Employment Verification",
        "version": "1.0",
        "requested_attributes": {
          "verifyEmployeeInfo": {
            "names": ["firstName", "lastName", "employeeId"],
            "restrictions": [
              { "cred_def_id": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default" }
            ]
          }
        },
        "requested_predicates": {}
      }
    }
  }'

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs/oob?requestType=INDY" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "emailId": ["alice@example.com", "bob@example.com"],
    "isShortenUrl": true,
    "proofFormats": {
      "indy": {
        "name": "Annual Compliance Check",
        "version": "1.0",
        "requested_attributes": {
          "verifyDept": {
            "name": "department",
            "restrictions": [
              { "schema_id": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0" }
            ]
          }
        },
        "requested_predicates": {}
      }
    }
  }'

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs/oob?requestType=PRESENTATIONEXCHANGE" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "isShortenUrl": true,
    "presentationDefinition": {
      "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
      "purpose": "Used for KYC verification.",
      "input_descriptors": [
        {
          "id": "banking_input_1",
          "name": "Bank Account Information",
          "schema": [
            { "uri": "https://bank-schemas.org/1.0.0/accounts.json" }
          ],
          "constraints": {
            "fields": [
              { "path": ["$.issuer"] }
            ]
          }
        }
      ]
    }
  }'

201 response

{
  "statusCode": 201,
  "message": "Proof request sent successfully",
  "data": {
    "invitationUrl": "http://agent.example.com/s/abc123",
    "proofId": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "state": "request-sent",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

Verify presentation

POST /orgs/:orgId/proofs/:proofId/verify Verify a proof presentation that a holder has submitted in response to a proof request. Required roles: owner, admin, verifier

Path parameters

string

required

UUID of the verifier organization.

string

required

UUID of the proof record to verify.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs/d8b9b81b-7232-4a7f-b9d3-4f7226129677/verify" \
  --header "Authorization: Bearer <your-jwt-token>"

201 response

{
  "statusCode": 201,
  "message": "Proof verified successfully",
  "data": {
    "id": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "isVerified": true,
    "state": "done",
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "threadId": "e1f2g3h4-5678-90ab-cdef-123456789012",
    "updatedAt": "2024-01-15T12:05:00.000Z"
  }
}

List proof presentations

GET /orgs/:orgId/proofs Retrieve all proof presentation records for an organization. Supports pagination, search, and sorting. Required roles: owner, admin, issuer, verifier, member, holder

Path parameters

string

required

UUID of the organization.

Query parameters

number

Page to retrieve. Min 1. Defaults to 1.

number

Records per page. Min 1, max 100. Defaults to 10.

string

Free-text search across proof records.

string

Field to sort by. Enum: createDateTime (default).

string

Sort direction. ASC or DESC (default).

Examples

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

200 response

{
  "statusCode": 200,
  "message": "Proof presentations fetched successfully",
  "data": {
    "totalItems": 1,
    "hasNextPage": false,
    "data": [
      {
        "id": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
        "state": "done",
        "isVerified": true,
        "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "threadId": "e1f2g3h4-5678-90ab-cdef-123456789012",
        "protocolVersion": "v1",
        "autoAcceptProof": "never",
        "createdAt": "2024-01-15T12:00:00.000Z",
        "updatedAt": "2024-01-15T12:05:00.000Z"
      }
    ]
  }
}

Get proof presentation by ID

GET /orgs/:orgId/proofs/:proofId Retrieve the details of a specific proof presentation record, including the submitted proof data. Required roles: owner, admin, issuer, verifier, member, holder

Path parameters

string

required

UUID of the organization.

string

required

UUID of the proof record to retrieve.

Response

object

Hide properties

string

UUID of the proof record.

string

Current state of the proof exchange. Common values: request-sent, presentation-received, done, abandoned.

boolean

Whether the submitted proof was cryptographically valid. Populated after verification.

string

UUID of the connection this proof was exchanged over.

string

DIDComm thread ID for this proof exchange.

string

Parent thread ID if this proof is part of a larger workflow.

string

DIDComm protocol version used.

string

Auto-acceptance mode configured for this proof.

object

The proof data submitted by the holder. Structure depends on the proof format.

string

ISO 8601 timestamp of creation.

string

ISO 8601 timestamp of last update.

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/proofs/d8b9b81b-7232-4a7f-b9d3-4f7226129677" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Proof presentation fetched successfully",
  "data": {
    "id": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "state": "done",
    "isVerified": true,
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "threadId": "e1f2g3h4-5678-90ab-cdef-123456789012",
    "protocolVersion": "v1",
    "autoAcceptProof": "never",
    "proofData": {
      "requested_proof": {
        "revealed_attrs": {
          "verifyEmployeeInfo": {
            "sub_proof_index": 0,
            "raw": "Alice",
            "encoded": "27034640024117331033063128044004318218486816931520886405535659934417438781507"
          }
        }
      }
    },
    "createdAt": "2024-01-15T12:00:00.000Z",
    "updatedAt": "2024-01-15T12:05:00.000Z"
  }
}

Status	Description
`400 Bad Request`	`proofId` is not a valid UUID.
`404 Not Found`	No proof record found with that ID.

Get verified proof details

GET /orgs/:orgId/verified-proofs/:proofId Retrieve the revealed attribute values and verification status of a completed proof presentation. Required roles: owner, admin, issuer, verifier, member, holder

Path parameters

string

required

UUID of the organization.

string

required

ID of the verified proof record.

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/verified-proofs/d8b9b81b-7232-4a7f-b9d3-4f7226129677" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Verified proof details fetched successfully",
  "data": {
    "proofId": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "isVerified": true,
    "revealedAttributes": {
      "firstName": "Alice",
      "lastName": "Smith",
      "employeeId": "EMP-1042"
    },
    "connectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "verifiedAt": "2024-01-15T12:05:00.000Z"
  }
}

Delete verification records

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

Path parameters

string

required

UUID of the organization whose verification records will be deleted.

Examples

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

200 response

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

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

​Base path

​Authentication

​Role-based access

​Endpoints

Send proof request

Send OOB proof request

Verify presentation

List proof presentations

Get proof presentation

Get verified proof details

Delete verification records

​Send proof request

​Path parameters

​Query parameters

​Request body

​Examples

​Send out-of-band proof request

​Path parameters

​Query parameters

​Request body

​Examples

​Verify presentation

​Path parameters

​Examples

​List proof presentations

​Path parameters

​Query parameters

​Examples

​Get proof presentation by ID

​Path parameters

​Response

​Examples

​Get verified proof details

​Path parameters

​Examples

​Delete verification records

​Path parameters

​Examples

Base path

Authentication

Role-based access

Endpoints

Send proof request

Path parameters

Query parameters

Request body

Examples

Send out-of-band proof request

Path parameters

Query parameters

Request body

Examples

Verify presentation

Path parameters

Examples

List proof presentations

Path parameters

Query parameters

Examples

Get proof presentation by ID

Path parameters

Response

Examples

Get verified proof details

Path parameters

Examples

Delete verification records

Path parameters

Examples