Create a presentation preset

This page covers the authoring concerns: naming, common pitfalls, and decisions only the author can make.

curl -X POST "https://test.didxtech.com/me-creds/api/v1/presets/presentations" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "basic-identity-request",
    "templateName": "Basic Identity Request",
    "templateDescription": "Standard request for basic identity information",
    "templateCredentials": [
      {
        "format": "sd-jwt-vc",
        "name": "Basic Identity Credential",
        "description": "A credential containing basic identity information",
        "type": "https://didx.co.za/vct/didx/basic-identity",
        "attributes": {
          "firstName": { "type": "string" },
          "lastName": { "type": "string" }
        },
        "trustedIssuers": [
          {
            "kind": "did",
            "did": "did:web:sarb.gov.za",
            "name": "South African Reserve Bank"
          },
          {
            "kind": "x509",
            "certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
            "name": "Department of Home Affairs"
          }
        ]
      }
    ]
  }'

Authoring guidance

Below is the part that’s specific to authoring: decisions only the author makes, and the common pitfalls.

Choose the `code` carefully

Your tenant alias is automatically prepended as the author, so code: "basic-identity-request" becomes the canonical id <your-alias>:basic-identity-request. That id is what verifiers will pass as presetId for the lifetime of the preset. Presets are immutable once published, so fixing a typo later means publishing -v2 and migrating consumers. Keep the code short, lowercase, hyphen-separated, and meaningful on its own (identity-kyc, not req1).

Write the description for someone scanning a list

templateName and templateDescription are what verifiers see when browsing the preset catalogue. Be specific in the description. “Identity proof for KYC onboarding, with first name, last name, and verified flag” is far more useful than “Identity request”.

Make sure `type` matches what issuers issue

The templateCredentials[].type URI must exactly match the credential type that issuers put on the credentials they produce. If issuers issue https://didx.co.za/vct/didx/basic-identity and your preset asks for https://didx.co.za/vct/didx/basic-id, the request will not match, even if the contents are otherwise compatible. Coordinate with the issuers in your ecosystem.

Almost always specify `trustedIssuers` explicitly

Leaving trustedIssuers empty (or omitting it) accepts any issuer of this credential type, which is rarely what a real verifier wants. List the specific issuers whose credentials you trust. Choose a name for each issuer that the end user will recognise. The wallet shows it during the consent step, so “South African Reserve Bank” is better than “sarb-prod-1”.

Updating and removing presets

The current API supports creating presets and reading them; it does not expose update or delete endpoints. Treat each published preset as immutable. If you need to change a shape, publish a new preset (e.g. bump code to basic-identity-request-v2) and migrate consumers.

What consumers do with your preset

Once published, verifiers reference your preset by its canonical id (<your-alias>:basic-identity-request). They pass that id when creating a presentation request; that’s all they need to do on their side.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Create a presentation preset