Step 2: Create Credential Template

Overview

A credential template defines the schema for a verifiable credential — what attributes it contains, which are required, and which are always disclosed to verifiers. Templates are reusable: create one “Web Development Completion” template and use it to credential hundreds of youth.

You provide a human-readable code. The API uses it to generate a Verifiable Credential Type (VCT) URI — the unique identifier that connects issuers to verifiers across the ecosystem. Share this type URI with any verifying partner who needs to request credentials of this type.

Endpoint

POST https://test.didxtech.com/me-creds/api/templates/credentials

Request

curl -X POST "https://test.didxtech.com/me-creds/api/templates/credentials" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialFormat": "sd-jwt",
    "name": "Web Development Completion",
    "code": "course-completion",
    "description": "Issued to youth who complete the Umuzi web development programme",
    "attributes": {
      "programmeName": {
        "type": "string",
        "name": "Programme Name",
        "description": "Name of the completed programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "completionDate": {
        "type": "string",
        "name": "Completion Date",
        "description": "Date the youth completed the programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "fullName": {
        "type": "string",
        "name": "Full Name",
        "description": "Youth'\''s full name",
        "required": true,
        "alwaysDisclosed": true
      },
      "skillsCovered": {
        "type": "string",
        "name": "Skills Covered",
        "description": "Comma-separated list of skills covered in the programme",
        "required": true,
        "alwaysDisclosed": false
      },
      "assessmentScore": {
        "type": "string",
        "name": "Assessment Score",
        "description": "Final assessment score (percentage)",
        "required": false,
        "alwaysDisclosed": false
      }
    }
  }'

Request Body Fields

Field	Type	Required	Description
`credentialFormat`	string	Yes	Credential format: `sd-jwt`, `mdoc`, or `preset` (to create from an ecosystem preset)
`name`	string	Yes	Human-readable name for the template
`code`	string	Yes	Short identifier (e.g. `course-completion`). Alphanumeric, hyphens, and underscores only. The API uses this to generate the full VCT URI returned in the `type` field.
`description`	string	No	Description of what this credential represents
`attributes`	object	Yes	Key-value map of attribute definitions (see below)

Attribute Fields

Each attribute in the template defines a data field on the credential:

Field	Type	Description
`type`	string	Data type (`string`, `date`, etc.)
`name`	string	Human-readable label shown in the youth’s wallet
`description`	string	Description of the attribute
`required`	boolean	Whether this attribute must be present when issuing
`alwaysDisclosed`	boolean	If `true`, this attribute is always shared when the credential is presented — the youth cannot withhold it

Selective Disclosure Design

Think carefully about alwaysDisclosed. This is a first-class concept, not a footnote:

alwaysDisclosed: true — The attribute is always visible to verifiers. Use for essential information like programme name and completion date.
alwaysDisclosed: false — The youth chooses whether to share this attribute. Use for sensitive information like assessment scores, personal identifiers, or anything the youth might reasonably want to keep private.

In the example above, Thandi can share her “Web Development Completion” credential with an employer while withholding her assessment score — that’s her choice, not the issuer’s or the verifier’s.

Response

HTTP 200 OK

{
  "data": {
    "id": "tpl_6421a8905c17830c188e2e2f",
    "name": "Web Development Completion",
    "description": "Issued to youth who complete the Umuzi web development programme",
    "type": "https://didx.co.za/vct/didx/course-completion",
    "format": "sd-jwt-vc",
    "attributes": {
      "programmeName": {
        "type": "string",
        "name": "Programme Name",
        "description": "Name of the completed programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "completionDate": {
        "type": "string",
        "name": "Completion Date",
        "description": "Date the youth completed the programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "fullName": {
        "type": "string",
        "name": "Full Name",
        "description": "Youth's full name",
        "required": true,
        "alwaysDisclosed": true
      },
      "skillsCovered": {
        "type": "string",
        "name": "Skills Covered",
        "description": "Comma-separated list of skills covered in the programme",
        "required": true,
        "alwaysDisclosed": false
      },
      "assessmentScore": {
        "type": "string",
        "name": "Assessment Score",
        "description": "Final assessment score (percentage)",
        "required": false,
        "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/templates/credentials/tpl_6421a8905c17830c188e2e2f"
  }
}

Key Response Fields

Field	Description
`id`	Unique template identifier — save this for issuing credentials in Step 3
`type`	The VCT URI generated from your `code`. Share this with verifying partners — it’s how they request credentials of this type.
`format`	`sd-jwt-vc` — Selective Disclosure JSON Web Token, enabling per-attribute disclosure control
`status`	`active` once the template is ready for use

Save the id (needed for Step 3: Issue a Credential) and the type URI (share with verifying partners).

Listing Credential Templates

Retrieve all credential templates for your organisation:

curl -X GET "https://test.didxtech.com/me-creds/api/templates/credentials" \
  -H "Authorization: Bearer <access_token>"

Returns an array of all templates with their id, name, type, status, and attributes.

Ecosystem Presets

YoID provides ecosystem presets — standardised credential structures for common use cases. Partners can create a template directly from a preset, or customise one based on a preset.

Impact Verification (from preset)

{
  "name": "Community Impact Verification",
  "description": "Issued to youth who complete a verified impact activity",
  "code": "impact-verified",
  "attributes": {
    "activityName": {
      "type": "string", "name": "Activity Name",
      "required": true, "alwaysDisclosed": true
    },
    "fullName": {
      "type": "string", "name": "Full Name",
      "required": true, "alwaysDisclosed": true
    },
    "completionDate": {
      "type": "string", "name": "Completion Date",
      "required": true, "alwaysDisclosed": true
    },
    "impactMetric": {
      "type": "string", "name": "Impact Metric",
      "required": true, "alwaysDisclosed": false
    }
  }
}

Programme Completion (customised from preset)

{
  "name": "Digital Skills Programme Completion",
  "description": "Issued to youth who complete a digital skills training programme",
  "code": "digital-skills",
  "attributes": {
    "programmeName": {
      "type": "string", "name": "Programme Name",
      "required": true, "alwaysDisclosed": true
    },
    "fullName": {
      "type": "string", "name": "Full Name",
      "required": true, "alwaysDisclosed": true
    },
    "completionDate": {
      "type": "string", "name": "Completion Date",
      "required": true, "alwaysDisclosed": true
    },
    "modulesCompleted": {
      "type": "string", "name": "Modules Completed",
      "required": true, "alwaysDisclosed": false
    }
  }
}

Getting Started

For Learning & Impact Partners

For Employers & Opportunity Providers

Reference

Step 2: Create Credential Template

Overview

Endpoint

Request

Request Body Fields

Attribute Fields

Selective Disclosure Design

Response

Key Response Fields

Listing Credential Templates

Ecosystem Presets

​Overview

​Endpoint

​Request

​Request Body Fields

​Attribute Fields

​Selective Disclosure Design

​Response

​Key Response Fields

​Listing Credential Templates

​Ecosystem Presets

Overview

Endpoint

Request

Request Body Fields

Attribute Fields

Selective Disclosure Design

Response

Key Response Fields

Listing Credential Templates

Ecosystem Presets