SD-JWT credential preset

This page walks through the shape of an SD-JWT credential preset field by field. For the mDoc shape, see mDoc credential preset.

SD-JWT in one minute: the VCT

The VCT (Verifiable Credential Type) is a URI, defined by the SD-JWT-VC specification, that names the kind of credential. It’s the credential’s type identifier. A verifier looking at a presented credential reads its vct value to know what kind of credential it is, what fields it carries, and how to interpret them. Two credentials with the same VCT are the same kind of credential. The URI itself doesn’t need to resolve to anything, but the convention is that it could, pointing to a published metadata document describing the credential type, schema, and display rules. For URL-shaped VCTs the document lives at the URL itself; for non-URL VCTs (such as a urn:) the owning ecosystem publishes it out of band. The VCT is what links everyone who touches the credential:

The preset declares the VCT in its templateType.
The issued credential carries the VCT in its vct claim.
The presentation request uses the VCT in templateCredentials[].type to filter the holder’s wallet down to credentials of the right kind.

The platform keeps the first two aligned automatically: a credential issued from the preset carries the preset’s templateType verbatim as its vct. The presentation request is the one place where alignment is on you. Ask for a different type and the wallet won’t surface the right credentials, so verification never happens.

The shape, end to end

This is a create request. Only code, templateName, templateDescription, and templateAttributes are required, because the /sd-jwt endpoint defaults credentialFormat for you:

{
  "credentialFormat": "sd-jwt",
  "code": "basic-identity",
  "namespace": "public",
  "templateName": "Basic Identity Credential",
  "templateDescription": "Standard basic identity credential",
  "templateAttributes": {
    "firstName": {
      "type": "string",
      "name": "First Name",
      "required": true,
      "alwaysDisclosed": false
    },
    "lastName": {
      "type": "string",
      "name": "Last Name",
      "required": true,
      "alwaysDisclosed": false
    }
  },
  "issuerConfig": { "signer": "did:web" },
  "validUntil": { "start": "validFrom", "future": { "years": 5 } },
  "branding": { "backgroundColor": "#0066CC", "textColor": "#FFFFFF" }
}

The response adds the fields the platform owns: id, author, createdAt, updatedAt, and templateType. With no type sent, templateType here comes back as $BASE_URL/vct/YOUR_ALIAS/basic-identity.

Identifier and metadata

The shared metadata fields (id, author, code, namespace, templateName, templateDescription, credentialFormat) are documented on the credential presets intro, including public versus private presets. The fields specific to SD-JWT are below.

`type` / `templateType` (the VCT)

The VCT for this preset (see SD-JWT in one minute). Send it as type; it comes back as templateType. Use either a platform VCT URL ($BASE_URL/vct/YOUR_ALIAS/CODE) or an external urn: URI. The platform does not support other http(s) URLs, and a platform URL must match your own tenant alias, so you cannot claim another tenant’s VCT path. type is optional. Omit it and the platform builds one from your code, giving $BASE_URL/vct/YOUR_ALIAS/CODE. Supply it only when you need a specific type, typically an external urn: you’re conforming to.

Platform VCT URLs are rooted at your environment’s own host, so the same code yields a different VCT on each environment. On test it is https://test.didxtech.com/vct/acme/staff-card, and production uses a different host. The platform writes the VCT into every credential issued from the preset, and it is what verifiers match on, so a credential issued on one environment will not satisfy a request built for another. Use an external urn: when you need one type across environments.

`branding`

Optional card styling: backgroundColor, textColor, and backgroundImageUrl. Colours must be 6-digit hex. The background image should be 16:9, PNG or JPEG, and under 1 MB. It is fixed at creation like everything else on a preset, so set it now. See Branding.

`issuerConfig`

How the platform signs credentials issued from this preset:

{ "signer": "did:web" }
// or
{ "signer": "certificate", "keyType": "P-256" }

did:web, the default. The platform signs credentials with the tenant’s did:web DID. Verifiers fetch the DID document to validate the signature.
certificate. The platform signs credentials with an x509 certificate from the tenant’s certificate pool. The optional keyType (P-256 or Ed25519) narrows the selection to a specific algorithm.

`validUntil`

How long the issued credentials remain valid. This is optional, and the default depends on your signer:

// did:web signer (the default)
{ "start": "validFrom", "future": { "years": 5 } }

// certificate signer
{ "start": "issuance", "future": { "days": 365 } }

Field	What it is
`start`	When the validity window starts counting. `"validFrom"` for DID-signed credentials, `"issuance"` when `signer` is `certificate`.
`future.days` / `future.months` / `future.years`	The duration of the window. Specify any combination; the total must be greater than zero.

start: "issuance" is capped at 365 days total. Anything longer returns a 400, Certificate issuance validUntil must not exceed 365 days total. Months count as 30 days and years as 365 for this check, so { "years": 1, "days": 1 } fails. This layer enforces no cap on start: "validFrom".

start: "validFrom" is not permitted with a certificate signer. Certificates must use "issuance".

`templateAttributes`: the credential’s fields

This is a flat map from attribute name to its definition. Each entry expresses a field on the credential and how it should behave at presentation time.

"firstName": {
  "type": "string",
  "name": "First Name",
  "required": true,
  "alwaysDisclosed": false
}

Field	What it is
`type`	Data type. Primitives: `string`, `number`, `boolean`, `date`. Compound: `object` (with `properties`), `array` (with `items`).
`name`	Human-readable label the wallet shows the holder (for example `"First Name"`, not `"firstName"`).
`description`	Optional explanation of the attribute.
`required`	Whether the issuer must supply a value for this attribute when issuing.
`alwaysDisclosed`	Whether the wallet always reveals the attribute at presentation, regardless of selective disclosure.

The attribute keys you declare (for example firstName and lastName) are what issuers pass under attributes when calling the issuance endpoint, and what verifiers ask for in a presentation request. They become the JSON keys on the issued credential itself.

Nested objects and arrays

SD-JWT supports nested attribute structures. An object attribute carries its own properties map; an array attribute carries an items schema:

"address": {
  "type": "object",
  "name": "Address",
  "required": false,
  "alwaysDisclosed": false,
  "properties": {
    "country": {
      "type": "string",
      "name": "Country",
      "required": true,
      "alwaysDisclosed": true
    }
  }
},
"nationalities": {
  "type": "array",
  "name": "Nationalities",
  "required": false,
  "alwaysDisclosed": false,
  "items": { "type": "string" }
}

`alwaysDisclosed` and selective disclosure

For SD-JWT credentials, the holder controls what they share on a per-presentation basis. alwaysDisclosed: false (the default) means the holder can withhold an attribute when they present the credential; alwaysDisclosed: true means the wallet always reveals it. Set alwaysDisclosed: 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. To issue against a preset, see Issue a credential.

Overview

User Onboarding

Issuance

Verification

Branding

Webhooks

Custom Templates (advanced)

Errors

SD-JWT in one minute: the VCT

The shape, end to end

Identifier and metadata

`type` / `templateType` (the VCT)

`branding`

`issuerConfig`

`validUntil`

`templateAttributes`: the credential’s fields

Nested objects and arrays

`alwaysDisclosed` and selective disclosure

​SD-JWT in one minute: the VCT

​The shape, end to end

​Identifier and metadata

​type / templateType (the VCT)

​branding

​issuerConfig

​validUntil

​templateAttributes: the credential’s fields

​Nested objects and arrays

​alwaysDisclosed and selective disclosure

SD-JWT in one minute: the VCT

The shape, end to end

Identifier and metadata

`type` / `templateType` (the VCT)

`branding`

`issuerConfig`

`validUntil`

`templateAttributes`: the credential’s fields

Nested objects and arrays

`alwaysDisclosed` and selective disclosure