Credential definitions

Create and manage credential definitions that bind a schema to an issuer’s cryptographic keys, enabling verifiable credential issuance.

A credential definition (cred def) binds a schema to an issuer’s public keys on the ledger. It establishes the cryptographic material needed to issue and verify AnonCreds credentials. Each credential definition:

• References a specific schema by its ledger ID (schemaLedgerId).
• Is tagged so an issuer can have multiple cred defs for the same schema (for example, for different departments or purposes).
• Optionally supports revocation, allowing the issuer to revoke credentials after issuance.

Credential definitions are write-once and ledger-anchored. They cannot be updated after creation.

Base path

All endpoints are rooted at /orgs/:orgId/cred-defs.

Authentication

Every endpoint requires a JWT bearer token.

Authorization: Bearer <your-jwt-token>

Role-based access

Operation	Required roles
Create credential definition	owner, admin
Read credential definitions	owner, admin, issuer, verifier, member

Endpoints

Create credential definition

POST /orgs/:orgId/cred-defs — Register a new credential definition on the ledger.

List credential definitions

GET /orgs/:orgId/cred-defs — Retrieve all credential definitions for an organization.

Get credential definition

GET /orgs/:orgId/cred-defs/:credDefId — Fetch a specific credential definition by its ledger ID.

---

Create credential definition

POST /orgs/:orgId/cred-defs

Creates a new credential definition and submits it to the ledger. The credential definition is derived from an existing schema.

Required roles: owner, admin

Path parameters

orgId · string · required

UUID of the organization creating the credential definition.

Request body

tag · string · required

A tag that distinguishes this credential definition from others using the same schema. Common values: "default", "revocable", or any custom identifier. Example: "employee-v1".

schemaLedgerId · string · required

The ledger ID of the schema this credential definition is derived from. Example: "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0".

revocable · boolean · required

Whether credentials issued using this definition support revocation. When true, a revocation registry is also created on the ledger. Defaults to false.

orgDid · string

Override the organization’s DID used to write the credential definition. Defaults to the org’s primary DID.

Response

statusCode · number

201 on success.

message · string

Human-readable result message.

data · object

Hide properties

id · string

Platform-internal UUID for this credential definition record.

credentialDefinitionId · string

The credential definition’s ID on the ledger. Format: "<issuerDid>:3:CL:<schemaSeqNo>:<tag>". Example: "WgWxqztrNooG92RXvxSTWv:3:CL:123:default".

tag · string

The tag provided at creation time.

schemaLedgerId · string

The schema this cred def is derived from.

revocable · boolean

Whether revocation is enabled.

orgId · string

UUID of the owning organization.

createdBy · string

UUID of the user who created the record.

createdAt · string

ISO 8601 timestamp of creation.

Examples

non-revocable

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/cred-defs" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "tag": "default",
    "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
    "revocable": false
  }'

201 response

{
  "statusCode": 201,
  "message": "Credential definition created successfully",
  "data": {
    "id": "b1e5f231-4c56-7a89-bc01-d234e567f890",
    "credentialDefinitionId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default",
    "tag": "default",
    "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
    "revocable": false,
    "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdBy": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "createdAt": "2024-01-15T09:30:00.000Z"
  }
}

Status	Description
400 Bad Request	orgId is not a valid UUID, or required fields are missing or invalid.
401 Unauthorized	Missing or invalid bearer token.
403 Forbidden	User does not have owner or admin role.
409 Conflict	A credential definition with the same schema and tag already exists on the ledger.

---

List credential definitions

GET /orgs/:orgId/cred-defs

Retrieve all credential definitions belonging to an organization. Supports pagination, 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

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

searchByText · string

Free-text search across credential definition tags and schema IDs.

sorting · string

Field to sort by. Defaults to "id".

sortByValue · string

Sort direction. ASC or DESC (default).

revocable · boolean

Filter by revocability. Defaults to true (show only revocable cred defs). Pass false to include non-revocable.

Examples

all credential definitions

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

200 response

{
  "statusCode": 200,
  "message": "Credential definitions fetched successfully",
  "data": {
    "totalItems": 2,
    "hasNextPage": false,
    "data": [
      {
        "id": "b1e5f231-4c56-7a89-bc01-d234e567f890",
        "credentialDefinitionId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default",
        "tag": "default",
        "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
        "revocable": false,
        "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "createdAt": "2024-01-15T09:30:00.000Z"
      },
      {
        "id": "c2e43f80-9f3a-4b12-835d-ecb9e4f12abc",
        "credentialDefinitionId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:revocable-v1",
        "tag": "revocable-v1",
        "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
        "revocable": true,
        "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "createdAt": "2024-01-15T09:45:00.000Z"
      }
    ]
  }
}

---

Get credential definition by ID

GET /orgs/:orgId/cred-defs/:credDefId

Fetch the details of a specific credential definition using its ledger ID.

Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId · string · required

UUID of the organization.

credDefId · string · required

The ledger credential definition ID. Example: "WgWxqztrNooG92RXvxSTWv:3:CL:123:default".

Examples

curl

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/cred-defs/WgWxqztrNooG92RXvxSTWv:3:CL:123:default" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Credential definition fetched successfully",
  "data": {
    "id": "b1e5f231-4c56-7a89-bc01-d234e567f890",
    "credentialDefinitionId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default",
    "tag": "default",
    "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
    "revocable": false,
    "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "publisherDid": "did:indy:WgWxqztrNooG92RXvxSTWv",
    "createdBy": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "createdAt": "2024-01-15T09:30:00.000Z",
    "updatedAt": "2024-01-15T09:30:00.000Z"
  }
}

Status	Description
400 Bad Request	credDefId is empty or malformed.
401 Unauthorized	Missing or invalid bearer token.
403 Forbidden	Authenticated user lacks the required role.
404 Not Found	No credential definition found with that ID.