Skip to main content
A credential preset is a published, ready-to-use credential shape: its format, attributes, and disclosure rules. Once published, anyone issuing the credential refers to it by its identifier (something like acme:degree-certificate or didx:basic-identity). To issue a credential, you pick a preset and supply the per-recipient values for the attributes it declares. Think of the preset as a blank form, with the fields, types, required markers, and disclosure rules all fixed. Issuance fills that form in for a specific person, and the platform signs it. The signed, filled-in form is the credential the user holds in their wallet.

​
Identifier and metadata

The metadata that identifies a preset is the same regardless of credential format:

​
Uniqueness

A preset is unique in two ways, both enforced at creation:
  • The id. AUTHOR:CODE is the human-readable preset identifier. The platform interpolates author from your tenant alias; you supply code, a lowercase hyphen-separated slug, in the create request.
  • The credential type. Each preset claims the credential type its credentials carry (templateType: the VCT for SD-JWT, the DocType for mDoc), and the claim is exclusive across the whole catalogue. Creating a preset whose credential type another preset already defines, yours or anyone else’s, returns a 409. A preset is the ecosystem-wide schema for its type, so two presets must never share a type with diverging definitions.

​
Public and private presets

Every preset sits in a namespace, set at creation with the namespace field. It controls who can see the preset in the catalogue, and it shows up in the preset’s id as a leading sigil: public is the default. Omit namespace and you publish to the shared catalogue. code is unique per author regardless of namespace, so acme:internal-badge and ~acme:internal-badge cannot both exist. The namespace belongs to the one preset rather than distinguishing two copies of it. There is no endpoint to change it afterwards, so choose it at creation. Listing presets reflects this. With no filter you see every public preset plus your own private ones; ?namespace=public narrows to the shared catalogue; ?namespace=private shows only your own. A private preset belonging to another tenant is invisible. It never appears in a listing, and fetching it by id returns 404 rather than 403, so the response never discloses that it exists. You issue against a private preset exactly as you would a public one, because the ~ is part of the id:
A private preset still claims its credential type across the entire catalogue. Privacy governs visibility, not the type reservation described above. If another tenant tries to publish a preset using a credential type your private preset already holds, they get a 409 that deliberately doesn’t identify the conflicting preset, because naming it would disclose something they aren’t allowed to see. Bear that in mind when choosing urn: types for private presets. Platform VCT URLs are already scoped to your tenant alias, so they cannot collide.
Not to be confused with the attribute namespaces inside an mDoc credential (org.iso.18013.5.1 and friends). Those group claims within a credential; this one controls catalogue visibility. See mDoc credential preset.

​
Immutability

Once published, a preset is immutable. The API supports creating and reading presets, and does not expose update or delete endpoints. We deliberately do not permit removal:
  • Issuers may already have issued credentials against the preset. Those credentials stay in wallets and keep verifying long after issuance, and the preset is the published definition of what they mean.
  • Removal would free up the preset’s credential type, letting someone re-create it with a different schema or different semantics. Verifiers matching on that type would then face two generations of incompatible credentials under one identifier.
If a preset no longer fits, publish a new one (for example acme:degree-certificate-v2) and migrate issuers to it. The identifier you choose at creation lives forever, so choose the slug carefully. Immutability covers the preset’s branding block too. The card colours you set at creation are the ones its credentials keep. See Branding.

​
Two formats, two shapes

templateAttributes, templateType, issuerConfig, and validUntil all differ between SD-JWT and mDoc. The two formats use different attribute structures, different signer options, and different validity rules.

SD-JWT credential preset

The default for most credentials. It has selective disclosure built in and wide wallet support.

mDoc credential preset

Use this for ISO 18013-5 credentials such as mobile driving licences and government-issued ID.

​
Three paths

Browse a credential preset

Find a preset already published by DIDx or another publisher and issue against it. There is no setup and no design work.

Create an SD-JWT preset

Publish your own SD-JWT credential shape so issuers can reference it by name.

Create an mDoc preset

Publish your own mDoc credential shape so issuers can reference it by name.

​
When a preset isn’t enough

If no preset matches your use case, you can define a one-off custom credential template instead. This is the exception, not the rule; most integrations don’t need it.