> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/credebl/platform/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## Base path

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

## Authentication

Every endpoint requires a JWT bearer token.

```http theme={null}
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

<CardGroup cols={2}>
  <Card title="Create credential definition" icon="plus" href="/api-reference/credentials/credential-definitions#create-credential-definition">
    `POST /orgs/:orgId/cred-defs` — Register a new credential definition on the ledger.
  </Card>

  <Card title="List credential definitions" icon="list" href="/api-reference/credentials/credential-definitions#list-credential-definitions">
    `GET /orgs/:orgId/cred-defs` — Retrieve all credential definitions for an organization.
  </Card>

  <Card title="Get credential definition" icon="magnifying-glass" href="/api-reference/credentials/credential-definitions#get-credential-definition-by-id">
    `GET /orgs/:orgId/cred-defs/:credDefId` — Fetch a specific credential definition by its ledger ID.
  </Card>
</CardGroup>

***

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

<ParamField path="orgId" type="string" required>
  UUID of the organization creating the credential definition.
</ParamField>

### Request body

<ParamField body="tag" type="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"`.
</ParamField>

<ParamField body="schemaLedgerId" type="string" required>
  The ledger ID of the schema this credential definition is derived from. Example: `"WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0"`.
</ParamField>

<ParamField body="revocable" type="boolean" required>
  Whether credentials issued using this definition support revocation. When `true`, a revocation registry is also created on the ledger. Defaults to `false`.
</ParamField>

<ParamField body="orgDid" type="string">
  Override the organization's DID used to write the credential definition. Defaults to the org's primary DID.
</ParamField>

### Response

<ResponseField name="statusCode" type="number">
  `201` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result message.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string">
      Platform-internal UUID for this credential definition record.
    </ResponseField>

    <ResponseField name="credentialDefinitionId" type="string">
      The credential definition's ID on the ledger. Format: `"<issuerDid>:3:CL:<schemaSeqNo>:<tag>"`. Example: `"WgWxqztrNooG92RXvxSTWv:3:CL:123:default"`.
    </ResponseField>

    <ResponseField name="tag" type="string">
      The tag provided at creation time.
    </ResponseField>

    <ResponseField name="schemaLedgerId" type="string">
      The schema this cred def is derived from.
    </ResponseField>

    <ResponseField name="revocable" type="boolean">
      Whether revocation is enabled.
    </ResponseField>

    <ResponseField name="orgId" type="string">
      UUID of the owning organization.
    </ResponseField>

    <ResponseField name="createdBy" type="string">
      UUID of the user who created the record.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash non-revocable theme={null}
  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
    }'
  ```

  ```bash revocable theme={null}
  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": "revocable-v1",
      "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
      "revocable": true
    }'
  ```
</CodeGroup>

```json 201 response theme={null}
{
  "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

<ParamField path="orgId" type="string" required>
  UUID of the organization.
</ParamField>

### Query parameters

<ParamField query="pageNumber" type="number">
  Page to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="pageSize" type="number">
  Records per page. Min `1`, max `100`. Defaults to `10`.
</ParamField>

<ParamField query="searchByText" type="string">
  Free-text search across credential definition tags and schema IDs.
</ParamField>

<ParamField query="sorting" type="string">
  Field to sort by. Defaults to `"id"`.
</ParamField>

<ParamField query="sortByValue" type="string">
  Sort direction. `ASC` or `DESC` (default).
</ParamField>

<ParamField query="revocable" type="boolean">
  Filter by revocability. Defaults to `true` (show only revocable cred defs). Pass `false` to include non-revocable.
</ParamField>

### Examples

<CodeGroup>
  ```bash all credential definitions theme={null}
  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>"
  ```

  ```bash non-revocable only theme={null}
  curl --request GET \
    --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/cred-defs?revocable=false" \
    --header "Authorization: Bearer <your-jwt-token>"
  ```
</CodeGroup>

```json 200 response theme={null}
{
  "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

<ParamField path="orgId" type="string" required>
  UUID of the organization.
</ParamField>

<ParamField path="credDefId" type="string" required>
  The ledger credential definition ID. Example: `"WgWxqztrNooG92RXvxSTWv:3:CL:123:default"`.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  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>"
  ```
</CodeGroup>

```json 200 response theme={null}
{
  "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. |