Create an mDoc credential preset

This page covers authoring an mDoc credential preset: the request body, the decisions that only the author makes, and the common pitfalls. For the field-by-field shape walkthrough, see mDoc credential preset. For SD-JWT credentials, see Create an SD-JWT credential preset. mDoc presets describe credentials conforming to ISO 18013-5, typically mobile driving licences and government-issued ID. The shape and authoring concerns are different from SD-JWT.

Request

curl -X POST "$BASE_URL/me-creds/api/v1/presets/credentials/mdoc" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "national-id",
    "templateName": "National ID",
    "templateDescription": "South African national identity document",
    "type": "za.co.didx.national-id",
    "templateAttributes": {
      "za.co.didx": {
        "properties": {
          "firstName": {
            "type": "string",
            "name": "First Name",
            "required": true
          },
          "dateOfBirth": {
            "type": "date",
            "name": "Date of Birth",
            "required": true
          }
        }
      }
    },
    "validUntil": { "future": { "days": 365 } },
    "issuerConfig": { "signer": "certificate", "keyType": "P-256" }
  }'

Guidance for authors

Choose the preset identifier (`code`)

The platform prepends your tenant alias as the author, so code: "national-id" becomes the canonical id YOUR_ALIAS:national-id. That id is what issuers will pass as presetId for the lifetime of the preset. Presets are immutable once published.

Choose the DocType (`type`)

type is the mDoc DocType, a short reverse-DNS string that identifies the document. It is unique platform-wide, one preset per credential type, and creating a preset whose DocType another preset already claims returns a 409. ISO 18013-5 mDLs use org.iso.18013.5.1.mDL; ecosystem credentials should follow whatever convention that ecosystem has set, for example za.gov.home-affairs.passport. The DocType matches verbatim against docType on the issued mDoc, and verifiers use it to identify the credential. If you’re targeting interoperability with an existing verifier population, pick the DocType they already expect. The value must be doctype-shaped: dot-separated segments of letters, digits, hyphens, and underscores (no URLs, no whitespace), at most 200 characters.

Group attributes into namespaces with intent

mDoc has no flat-attribute model, because every attribute lives inside a namespace. Use namespaces to group attributes that logically belong together or that come from a common authority. For ISO-18013-5-compliant credentials, follow the spec’s namespace conventions, for example org.iso.18013.5.1 for standard mDL fields. For ecosystem-specific extensions, use a namespace under the ecosystem’s domain.

These attribute namespaces are not the preset’s own namespace field, which is public or private and controls catalogue visibility. They share a word but not a scope.

Decide whether it belongs in the shared catalogue (`namespace`)

The preset’s top-level namespace defaults to public, publishing it for every tenant. Set it to private for internal or experimental credentials. The preset then only appears in your own listings, its id gains a ~ prefix (~acme:staff-card), and other tenants get a 404 if they try to fetch it. Private still reserves the DocType catalogue-wide, so choose type as carefully as you would for a public preset. See public and private presets.

Set `branding` now if you want it

branding controls how the credential’s card renders in the wallet, through backgroundColor, textColor, and backgroundImageUrl, with colours as 6-digit hex. It is fixed at creation along with everything else on the preset. See Branding.

Adding branding later means a new DocType. DocTypes are unique across the whole catalogue and you always set yours explicitly, so a replacement preset needs a DocType you have not used before. Verifiers requesting the old DocType will not match the rebranded credential. For an ISO-conformant type like org.iso.18013.5.1.mDL that is not an option, so get branding right the first time.

Plan around the 365-day validity cap

mDoc credentials are capped at 365 days of validity, counted from issuance. There’s no start: validFrom option as in SD-JWT, so the window always starts the moment you issue the credential. Plan reissuance and rotation accordingly. For credentials that need to live longer, the issuer has to re-issue annually, typically driven from the credential’s own expiry signals.

Overview

User Onboarding

Issuance

Verification

Branding

Webhooks

Custom Templates (advanced)

Errors

Request

Guidance for authors

Choose the preset identifier (`code`)

Choose the DocType (`type`)

Group attributes into namespaces with intent

Decide whether it belongs in the shared catalogue (`namespace`)

Set `branding` now if you want it

Plan around the 365-day validity cap

​Request

​Guidance for authors

​Choose the preset identifier (code)

​Choose the DocType (type)

​Group attributes into namespaces with intent

​Decide whether it belongs in the shared catalogue (namespace)

​Set branding now if you want it

​Plan around the 365-day validity cap

Request

Guidance for authors

Choose the preset identifier (`code`)

Choose the DocType (`type`)

Group attributes into namespaces with intent

Decide whether it belongs in the shared catalogue (`namespace`)

Set `branding` now if you want it

Plan around the 365-day validity cap