Skip to main content

Single, Batch, and Multi-Format Issuance

Procivis One enables you to issue single credentials, credentials in a batch, and the same credential in multiple formats in one issuance. These types of credentials behave differently. This page explains how these different kinds of issuance work.

Single vs. batch issuance​

When creating a credential schema, you can optionally set a batchSize. If you do not set a value for this, you will issue a single credential when you issue using this schema. If you do set a value for batchSize (must be at least 2), you will issue a batch credential.

Single credentials​

A single credential is issued once. These credentials are then reused by wallet users across multiple presentations. These credentials cannot be refreshed, and are valid until they expire, are suspended, or are revoked.

In the list and detail credential endpoints, these credentials appear as "type": "SINGLE".

Batch credentials​

Multiple credentials are issued at once — specifically, the number you specify for batchSize of the credential schema. The wallet uses a different holder-binding key for each credential; the batch is otherwise identical. The wallet then uses each credential only once. Depending on your configurations for expiration and refresh token lifetime, the wallet can refresh this credential and receive a new batch.

When you create a batch credential, the system creates a batch parent — a logical record that tracks and manages the batch — along with the individual batch items themselves, which are the credentials actually issued and presented. These appear as "type": "BATCH_PARENT" and "type": "BATCH_ITEM".

When you manage the batch parent credential — for example, suspending or revoking the parent — the system handles all batch items automatically. The status of a batch parent reflects the logical credential, since any given batch item may have differing statuses.

The batch item is the actual credential held in the wallet and used in presentations. While you can suspend or revoke a batch item, managing credentials using the batch parent is more appropriate for most use cases.

Multi-format issuance​

Credentials are issued in multiple formats when the following conditions are met:

When you fetch the details of a credential you can see all credential formats available on the schema, the formats which were offered and what happened with each offered credential:

GET /api/credential/v1/{id}

{
  "offeredFormats": [
    {
      "format": "MDOC",
      "state": "ACCEPTED"
    }
  ],
  "schema": {
    "formats": [
      {
        "ecosystemSchemaId": "org.example.membership",
        "format": "MDOC",
      },
      {
        "ecosystemSchemaId": "membership_example",
        "format": "SD_JWT_VC",
      }
    ]
  }
}

In this example, both MDOC and SD_JWT_VC formats were available, but only MDOC was used during credential creation. For each format offered, state provides the status of the offer in relation to the holder, with the following values:

  • PENDING — the offer has not been accepted
  • ACCEPTED — the credential has been issued
  • REJECTED — the wallet has notified that it has deleted the credential (not supported by all wallets)

Expiration, suspension, and revocation​