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 "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 preset identifier (`code`)

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. 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 is already claimed by another is rejected with a 409. 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. 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 — 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).

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Request

Authoring guidance

Choose the preset identifier (`code`)

Choose the DocType (`type`)

Group attributes into namespaces with intent

Plan around the 365-day validity cap

​Request

​Authoring guidance

​Choose the preset identifier (code)

​Choose the DocType (type)

​Group attributes into namespaces with intent

​Plan around the 365-day validity cap

Request

Authoring guidance

Choose the preset identifier (`code`)

Choose the DocType (`type`)

Group attributes into namespaces with intent

Plan around the 365-day validity cap