Custom credential template (advanced)

Most integrations don’t need this page. If you can issue against a published preset, do that. See Issue a credential. Custom templates are for cases where you need a credential shape that no preset covers (private credentials, internal-only schemes, experiments).

Overview

A credential template defines the schema for a verifiable credential: what attributes it carries, their types, and which are always disclosed. Create it once and reuse it to issue many credentials with different data. Use a custom template when:

No published preset matches the credential you want to issue.
You’re building a private or internal credential that shouldn’t live in a shared catalogue.
You need fine-grained control over alwaysDisclosed, attribute types, or the type URI.

The type field you set in a credential template is what verifiers later match against in the credential presentation flow.

Pick the right endpoint for your format

The API exposes a separate POST endpoint per credential format. Use the one that matches the credential you want to define:

SD-JWT: POST /templates/credentials/sd-jwt
mDoc: POST /templates/credentials/mdoc

A generic POST /templates/credentials exists too (it dispatches by credentialFormat in the body), but the format-specific endpoints have a single, format-shaped request body and are simpler to work with.

Request (SD-JWT)

curl -X POST "https://test.didxtech.com/me-creds/api/v1/templates/credentials/sd-jwt" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic Identity",
    "description": "First name and last name",
    "type": "https://didx.co.za/vct/didx/basic-identity",
    "attributes": {
      "firstName": {
        "type": "string",
        "name": "First Name",
        "description": "Given name",
        "required": true,
        "alwaysDisclosed": false
      },
      "lastName": {
        "type": "string",
        "name": "Last Name",
        "description": "Family name",
        "required": true,
        "alwaysDisclosed": false
      }
    }
  }'

`type`: naming the credential type

type carries the template’s credential type verbatim. It is what verifiers match against at presentation time, and it goes onto every credential issued from the template. The accepted shape depends on the format:

SD-JWT: the VCT, as a urn: URI (e.g. urn:eu.europa.ec.eudi:pid:1) or your own platform VCT URL (https://didx.co.za/vct/<your-alias>/...). Other http(s) URLs are rejected.
mDoc: the DocType, a dot-separated reverse-DNS string such as org.iso.18013.5.1.mDL.

SD-JWT templates additionally accept code instead of type, as a shortcut that projects to the platform VCT URL above (code: "basic-identity" becomes https://didx.co.za/vct/<your-alias>/basic-identity). Sending both is rejected with a 400, and code is not accepted on mDoc templates.

Attribute fields

Each attribute is a field on the credential. The following properties configure each one:

Field	Type	Description
`type`	string	Data type (`string`, `date`, etc.)
`name`	string	Human-readable label for the attribute
`description`	string	Description of the attribute
`required`	boolean	Whether this attribute must be present
`alwaysDisclosed`	boolean	If `true`, this attribute is always shared when the credential is presented

Response

HTTP 201 Created

{
  "data": {
    "id": "tpl_6421a8905c17830c188e2e2f",
    "name": "Basic Identity",
    "description": "First name and last name",
    "type": "https://didx.co.za/vct/didx/basic-identity",
    "format": "sd-jwt-vc",
    "attributes": {
      "firstName": {
        "type": "string",
        "name": "First Name",
        "description": "Given name",
        "required": true,
        "alwaysDisclosed": false
      },
      "lastName": {
        "type": "string",
        "name": "Last Name",
        "description": "Family name",
        "required": true,
        "alwaysDisclosed": false
      }
    },
    "createdAt": "2025-01-20T11:27:37.051Z",
    "updatedAt": "2025-01-20T11:27:37.051Z",
    "archivedAt": null,
    "status": "active"
  },
  "links": {
    "self": "https://test.didxtech.com/me-creds/api/v1/templates/credentials/sd-jwt/tpl_6421a8905c17830c188e2e2f",
    "issuances": "https://test.didxtech.com/me-creds/api/v1/templates/credentials/sd-jwt/tpl_6421a8905c17830c188e2e2f/issuances"
  },
  "meta": {
    "version": "1.0",
    "totalAttributes": 2
  }
}

Key response fields

Field	Description
`id`	Unique template identifier. Pass it as `credentialTemplateId` when issuing
`type`	The credential type, verbatim as supplied. Used by verifiers during presentation
`format`	The credential format the template uses (e.g. `sd-jwt-vc`)
`status`	`active` once the template is ready for use

Save the id from the response. You’ll need it as the credentialTemplateId in Issue a credential.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Overview

Pick the right endpoint for your format

Request (SD-JWT)

`type`: naming the credential type

Attribute fields

Response

Key response fields

​Overview

​Pick the right endpoint for your format

​Request (SD-JWT)

​type: naming the credential type

​Attribute fields

​Response

​Key response fields

Overview

Pick the right endpoint for your format

Request (SD-JWT)

`type`: naming the credential type

Attribute fields

Response

Key response fields