Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt

Use this file to discover all available pages before exploring further.

​
Three objects, easy to confuse

Three terms appear across the API and are easy to blur together. The mental model:
Templates describe shape. Presets are pre-built shapes. Issuances describe specific events.
The schema for a credential or a presentation request. Defines what attributes exist, their types, and whether they are alwaysDisclosed. Define once, use for many issuances.Example: a “University Student Card” credential template that specifies studentId, fullName, enrollmentDate, and degreeProgram.Templates live under /templates/credentials (for credential templates) and /templates/presentations (for presentation templates).
A named, pre-built starting point for a credential or presentation template, defined at an ecosystem level. A bank, a university, or a national scheme authors presets relevant to its community. DIDx also publishes presets for cross-cutting patterns. Instead of defining every attribute from scratch, you can create a template “from preset” by referencing a presetId (for example, didx:basic-identity), then override only the parts you need.Presets are exposed through /presets/credentials and /presets/presentations. Use them for common credential shapes where a standardised starting point already exists.
The actual instance. A specific credential offered to a specific user, or a specific request sent to a specific user. This is the object that gets a status, a webhook, and an audit trail.An issuance progresses through one of these statuses:
StatusMeaning
offeredThe issuance has been created and the credential offered to the holder; awaiting holder acceptance.
completedThe holder accepted the offer and the credential was issued in full.
partiallyIssuedThe holder accepted but only a subset of the offered credentials was successfully issued.
failedIssuance failed (for example, the holder rejected the offer or a downstream error occurred).
expiredThe offer was not actioned within its validity window.
A presentation request progresses through:
StatusMeaning
requestedThe presentation request has been created and dispatched; awaiting holder response.
verifiedThe holder presented credentials and verification succeeded.
failedVerification failed (for example, the holder rejected the request or a credential failed validation).
expiredThe request was not actioned within its validity window.
The same names appear as suffixes on the corresponding webhook event types — for example, openid4vc.issuance.offered, openid4vc.verification.verified. One additional webhook event, openid4vc.verification.data, is emitted only when the underlying Paradym project is configured to share presentation data via webhooks; this is not enabled by default.

​
How the pieces fit together

A typical issuer setup looks like this: 
Preset (optional starting point)
    │
    ▼
Template  ── defines shape, attributes, alwaysDisclosed ──  reusable
    │
    ▼
Issuance  ── one per credential offered ──  has status, webhooks, audit trail
And on the verifier side: 
Preset (optional starting point)
    │
    ▼
Presentation Template  ── defines what to ask for, plus Trusted Entities ──  reusable
    │
    ▼
Presentation Request  ── one per verification ──  has status, webhooks, audit trail
The separation matters: a template is the design of a credential or request, and you want to change it rarely. An issuance or presentation request is every time a credential is handed out or a verification is run, these scale with user activity. Keep templates stable; issuances will grow.