Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yoid.me/llms.txt

Use this file to discover all available pages before exploring further.

​
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

FieldTypeRequiredDescription
credentialFormatstringYesCredential format: sd-jwt, mdoc, or preset (to create from an ecosystem preset)
namestringYesHuman-readable name for the template
codestringYesShort 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.
descriptionstringNoDescription of what this credential represents
attributesobjectYesKey-value map of attribute definitions (see below)

​
Attribute Fields

Each attribute in the template defines a data field on the credential:
FieldTypeDescription
typestringData type (string, date, etc.)
namestringHuman-readable label shown in the youth’s wallet
descriptionstringDescription of the attribute
requiredbooleanWhether this attribute must be present when issuing
alwaysDisclosedbooleanIf 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

FieldDescription
idUnique template identifier — save this for issuing credentials in Step 3
typeThe VCT URI generated from your code. Share this with verifying partners — it’s how they request credentials of this type.
formatsd-jwt-vc — Selective Disclosure JSON Web Token, enabling per-attribute disclosure control
statusactive 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. 
{
  "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
    }
  }
}

{
  "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
    }
  }
}