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 Anatomy of an 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.

Endpoint

POST /presets/credentials/mdoc

Request

curl -X POST "https://test.didxtech.com/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" }
  }'

Authoring guidance

Choose the `code` carefully

Your tenant alias is automatically prepended 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. Unlike SD-JWT, the mDoc DocType (type) is not derived from the code. You supply both independently. Presets are immutable once published.

Choose the DocType (`type`) to match the spec or ecosystem

type is the mDoc DocType — a short reverse-DNS string that identifies the document. ISO 18013-5 mDLs use org.iso.18013.5.1.mDL; ecosystem credentials should follow whatever convention that ecosystem has set (e.g. 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.

Group attributes into namespaces with intent

mDoc has no flat-attribute model — 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 (e.g. org.iso.18013.5.1 for standard mDL fields). For ecosystem-specific extensions, use a namespace under the ecosystem’s domain.

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 — the window always starts the moment the credential is issued. Plan reissuance / rotation accordingly. For credentials that need to live longer, the issuer will need to re-issue annually (typically driven from the credential’s own expiry signals).

Updating and removing presets

The API supports creating and reading presets; it does not expose update or delete endpoints. Presets are immutable.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Endpoint

Request

Authoring guidance

Choose the `code` carefully

Choose the DocType (`type`) to match the spec or ecosystem

Group attributes into namespaces with intent

Plan around the 365-day validity cap

Updating and removing presets

​Endpoint

​Request

​Authoring guidance

​Choose the code carefully

​Choose the DocType (type) to match the spec or ecosystem

​Group attributes into namespaces with intent

​Plan around the 365-day validity cap

​Updating and removing presets

Endpoint

Request

Authoring guidance

Choose the `code` carefully

Choose the DocType (`type`) to match the spec or ecosystem

Group attributes into namespaces with intent

Plan around the 365-day validity cap

Updating and removing presets