Create an SD-JWT credential preset

This page covers authoring an SD-JWT credential preset: the request body, the decisions that only the author makes, and the common pitfalls. For the field-by-field shape walkthrough, see SD-JWT credential preset. For mDoc credentials, see Create an mDoc credential preset.

Request

curl -X POST "$BASE_URL/me-creds/api/v1/presets/credentials/sd-jwt" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "basic-identity",
    "templateName": "Basic Identity Credential",
    "templateDescription": "A basic identity credential template",
    "templateAttributes": {
      "firstName": {
        "type": "string",
        "name": "First Name",
        "required": true,
        "alwaysDisclosed": false
      },
      "lastName": {
        "type": "string",
        "name": "Last Name",
        "required": true,
        "alwaysDisclosed": false
      }
    }
  }'

Guidance for authors

Choose the preset identifier (`code`)

The platform prepends your tenant alias as the author, so code: "basic-identity" becomes the canonical preset id YOUR_ALIAS:basic-identity. That id is what issuers will pass as presetId for the lifetime of the preset. Presets are immutable once published. Keep the code short, lowercase, hyphen-separated, and meaningful on its own (degree-certificate, not cred1).

Choose the credential type (`type`)

type is the credential type (the VCT) carried by every credential issued against the preset. It is unique platform-wide, one preset per credential type, and creating a preset whose type another preset already claims returns a 409. Supply it verbatim in the optional type field, for example when an external ecosystem such as EUDI dictates the type:

{
  "code": "eudi-pid",
  "type": "urn:eu.europa.ec.eudi:pid:1",
  "templateName": "EUDI PID",
  ...
}

If you omit type, the platform infers it from the preset identifier. The preset acme:identity-1-0 projects to $BASE_URL/vct/acme/identity-1-0, which on test is https://test.didxtech.com/vct/acme/identity-1-0. Use either a urn: URI or your own platform VCT URL ($BASE_URL/vct/YOUR_ALIAS/...). The platform rejects other http(s) URLs, because every URL-shaped VCT it issues is platform-hosted and resolvable.

A projected VCT is rooted at the environment’s host, so it differs between environments. If you need one credential type to hold across environments, supply an external urn: instead of relying on the projection.

Decide whether it belongs in the shared catalogue (`namespace`)

namespace defaults to public, which publishes the preset for every tenant to see and issue against. Set it to private for internal or experimental credentials. The preset then only appears in your own listings, its id gains a ~ prefix (~acme:internal-badge), and other tenants get a 404 if they try to fetch it. Private still reserves the credential type catalogue-wide, so pick your type as carefully as you would for a public preset. See public and private presets.

Set `branding` now if you want it

branding controls how the credential’s card renders in the wallet, through backgroundColor, textColor, and backgroundImageUrl, with colours as 6-digit hex. It is fixed at creation along with everything else on the preset, so an unbranded preset stays unbranded. See Branding.

Adding branding later changes the credential type. Credential types are unique across the whole catalogue, so a replacement preset cannot reuse the old one. With a projected VCT a new code yields a new VCT, and with a urn: you must mint a new one. Verifiers matching on the old type stop matching the rebranded credential, and holders keep the unbranded credential they already have. Rebranding is a migration, not an edit.

Write the description for someone scanning a list

templateName and templateDescription are what issuers see when browsing the catalogue. Be specific in the description. “Basic identity credential carrying first name and last name” is far more useful than “Identity credential”.

Use `alwaysDisclosed: true` sparingly

For SD-JWT credentials, the holder normally controls what they share on a per-presentation basis. alwaysDisclosed: true removes that choice for a given attribute. Set it true only for fields whose presence is meaningful in itself, typically trust signals like a verified flag, where the credential carries no useful meaning without it. For ordinary personal data such as name and date of birth, leave it false and let the holder decide.

Pick `issuerConfig.signer` deliberately

did:web is the default. The platform signs credentials with the tenant’s did:web DID, and verifiers fetch the DID document to validate. Choose certificate only when you need x509-based signing (rarer for SD-JWT; common in regulated environments). The certificate option also caps the validity window at 365 days.

Overview

User Onboarding

Issuance

Verification

Branding

Webhooks

Custom Templates (advanced)

Errors

Request

Guidance for authors

Choose the preset identifier (`code`)

Choose the credential type (`type`)

Decide whether it belongs in the shared catalogue (`namespace`)

Set `branding` now if you want it

Write the description for someone scanning a list

Use `alwaysDisclosed: true` sparingly

Pick `issuerConfig.signer` deliberately

​Request

​Guidance for authors

​Choose the preset identifier (code)

​Choose the credential type (type)

​Decide whether it belongs in the shared catalogue (namespace)

​Set branding now if you want it

​Write the description for someone scanning a list

​Use alwaysDisclosed: true sparingly

​Pick issuerConfig.signer deliberately

Request

Guidance for authors

Choose the preset identifier (`code`)

Choose the credential type (`type`)

Decide whether it belongs in the shared catalogue (`namespace`)

Set `branding` now if you want it

Write the description for someone scanning a list

Use `alwaysDisclosed: true` sparingly

Pick `issuerConfig.signer` deliberately