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

orgId

string

required

UUID of the verifier organization.

Query parameters

requestType

string

required

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

Request body

v1 — single connection
v2 — multiple connections

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

connectionId

string

required

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

proofFormats

object

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

Show proofFormats.indy

attributes

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.

presentationDefinition

object

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

Show presentationDefinition fields

string

required

Unique identifier for this presentation definition.

purpose

string

Human-readable description of the verification purpose.

input_descriptors

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.

comment

string

Optional comment attached to the proof request.

autoAcceptProof

string

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

goalCode

string

Goal code for the proof request thread.

parentThreadId

string

Attach this proof request to an existing thread.

willConfirm

boolean

Whether the verifier will confirm receipt.

protocolVersion

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.

connectionId

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

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

orgId

string

required

UUID of the verifier organization.

Query parameters

requestType

string

required

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

Request body

proofFormats

object

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

Show proofFormats.indy

name

string

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

version

string

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

requested_attributes

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.).

requested_predicates

object

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

presentationDefinition

object

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

comment

string

Optional comment.

goalCode

string

Goal code for the proof request thread.

protocolVersion

string

DIDComm protocol version.

autoAcceptProof

string

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

isShortenUrl

boolean

Return a shortened invitation URL. Defaults to true.

emailId

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.

reuseConnection

boolean

Attempt to reuse an existing connection with the holder.

label

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

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

orgId

string

required

UUID of the verifier organization.

proofId

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

orgId

string

required

UUID of the organization.

Query parameters

pageNumber

number

Page to retrieve. Min 1. Defaults to 1.

pageSize

number

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

string

Free-text search across proof records.

sortField

string

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

sortBy

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

orgId

string

required

UUID of the organization.

proofId

string

required

UUID of the proof record to retrieve.

Response

data

object

Hide properties

string

UUID of the proof record.

state

string

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

isVerified

boolean

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

connectionId

string

UUID of the connection this proof was exchanged over.

threadId

string

DIDComm thread ID for this proof exchange.

parentThreadId

string

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

protocolVersion

string

DIDComm protocol version used.

autoAcceptProof

string

Auto-acceptance mode configured for this proof.

proofData

object

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

createdAt

string

ISO 8601 timestamp of creation.

updatedAt

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

orgId

string

required

UUID of the organization.

proofId

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

orgId

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.

Authentication

Organizations

Connections & Credentials

Ecosystem & Wallet

​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

Build docs developers (and LLMs) love

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