Skip to main content
Version: v0.25.0 (Latest)

Credential designs

A credential design is the tenant-owned definition of a credential type: which wire format it uses, which identifiers wallets and issuers match on, which claims exist (and whether they may be selectively disclosed), how labels appear per locale, and which card/render variants wallets may show.

Designs feed issuer metadata (credential_configurations_supported), issuance templates, and wallet display. They are not the same as a single issued credential instance.

Whether any design already exists depends on product onboarding and whether sample data was selected when the tenant was registered. This guide covers the Admin Console library and workbench, plus the credential-design REST API.

Audience: tenant admin (or platform operator in a tenant context).

Prerequisites: Onboard a tenant. For real issuance you usually also need Keys and DID for signing material. REST needs a tenant-scoped token.

Reference: Credential designs, Issuer designs, Render variants, Assets.

Schemas: Credential design API.

Guide variables useful for live Run: designId, asset and render-variant ids after create.

List designs​

The library is the inventory of credential types for this tenant. Each row is one design (alias, hosting mode, primary binding summary). From here you create, open, duplicate, refresh cached external designs, or delete.

Empty list means none were created and sample data did not seed any. That is normal for a clean production tenant.

Navigation: Resources > Credential Designs > Credential designs
Deep link: #resource=credentialDesigns&rarea=credential-designs

Credential designs list

Create a design​

Create starts a short dialog, then opens the full workbench for that design. The dialog only needs enough identity to register the type; claims, localization, and render come next in the workbench.

FieldWhy it matters
AliasShort handle inside the tenant. Used by operators and often by automation. Keep it stable.
Display nameDefault locale name shown to people (wallets, admin UI). Required to create.
FormatWire format: SD-JWT VC, W3C VC, or mdoc. Drives which primary identifier field appears.
VCT / type / doctypePrimary type identifier for that format (for example SD-JWT vct, W3C type, mdoc docType). Wallets and issuer metadata match on this. Required.
Credential configuration idOID4VCI configuration id advertised in issuer metadata. Optional at create, but needed before real OID4VCI issuance for that configuration.

After create, the console opens the design workbench so you can finish claims and display.

Create credential design dialog

Design workbench​

Opening a design (or finishing create) lands on a tabbed editor. Save when the design is consistent; validation errors map back to the tab that owns the field.

Overview​

Identity and format binding for the type:

  • Alias for operators and APIs.
  • Format and format-specific binding fields (VCT and hosting mode for SD-JWT, type/@context for W3C VC, doctype for mdoc, plus credential configuration id when you issue over OID4VCI).
  • Read-only metadata (content hash, created/updated) after the design has been saved.

Change format only when you understand that claim paths and wallet matching may no longer apply.

Credential design: Overview

Claims​

Claims are the data model of the credential: paths (or mdoc namespace paths), value kinds, widget hints, and selective disclosure policy where the format supports it (especially SD-JWT).

  • Add only claims you will populate at issuance or accept from a source system.
  • Mark disclosure carefully: over-disclosing defeats privacy goals; under-disclosing blocks verifiers that need a claim.
  • Nested claims form a tree; order and path must match what issuers and verifiers expect.
Credential design: Claims

Localization​

Human-readable strings (design name, description, claim labels, issuer name override) across locales. The default locale is the fallback; other locales can override or inherit.

Add locales your wallets and holders actually use. Incomplete localization produces English-only or missing labels at presentation time.

Credential design: Localization

Render (on the credential design)​

This tab only links library render variants to the design and picks preferred variants per locale. It does not own logo files or card colours. Create and polish variants under Render Variants, and upload binary files under Assets first.

If nothing is attached, wallets fall back to unbranded or product defaults. Prefer the card that matches the locale the holder will open.

Credential design: Render tab

Source JSON​

Raw design document for power users and copy/paste from known-good exports. Prefer the structured tabs for day-to-day edits. Apply JSON only when you understand the schema; invalid documents fail validation on save.

Credential design: Source JSON

Resolved preview​

Server-side resolution of the design for a chosen preview locale: effective displays, claims, and linked render after inheritance rules. Use it to verify what holders will see before you point issuance at the design.

Refresh after localization or render changes.

Credential design: Resolved preview

Format notes​

SD-JWT VC (for example EuPid)​

Use format SD-JWT VC, a stable vct, and a credential configuration id that will appear in OID4VCI metadata. Prefer selective disclosure policies that match the privacy profile of the credential.

mdoc (for example mDL)​

Use format mdoc and an ISO doctype (for example org.iso.18013.5.1.mDL). Claim paths use the ISO namespace. Portrait and similar binary claims need the correct value kinds.

Assets​

Assets are content-addressed files (logos, backgrounds, SVG templates) shared across the tenant. Upload once; many render variants and issuer designs can reference the same URI. The library does not define claims or OID4VCI configurations.

Upload before you expect logos on cards. Prefer compact PNG or SVG suitable for wallet card faces.

Navigation: Resources > Credential Designs > Assets
Deep link: #resource=credentialDesigns&rarea=assets
Reference: Assets

Library grid of uploaded files. Open a tile to see which render variants use that URI before you replace a logo in production.

Assets library

Upload picks type and file, shows a preview, then stores a stable URI (and integrity when the API returns one).

Upload asset

Render variants (library)​

A render variant is a reusable display recipe: simple card colours and logo, or an SVG template. Credential designs and issuer designs attach variants; they do not embed exclusive copies. Editing a shared variant changes every design that prefers it.

Author SIMPLE_CARD and SVG_TEMPLATE in the console. Other kinds may appear read-only when preserved from external systems.

Navigation: Resources > Credential Designs > Render Variants
Deep link: #resource=credentialDesigns&rarea=render-variants
Reference: Render variants

List and create​

List shows alias, kind, and locale applicability. Create with kind and alias (and template URI for SVG). Then open the variant to set colours, logo, background, and locale scope.

Render Variants listNew render variant

Edit a simple card​

Background and text colour, logo and optional background image from Assets, and which locales the card applies to. When a design has several variants, set preferred variants per locale on the credential design Render tab so EN and NL do not show the same art if you intended different brands.

Render variant simple card editor

Issuer branding​

An issuer design (console label Issuer Branding) is the face of the issuing organization, not a credential type. Display name, description, logo, and optional issuer-level render card are shared by every credential type that points at that issuer design. Bind the design to the correct issuer DID (or issuer instance) so wallet display matches the keys that signed the VC.

Create issuer branding when sample data did not seed it, or when a second issuer instance needs a different public name. Prefer assets already in the library for logos.

Navigation: Resources > Credential Designs > Issuer Branding
Deep link: #resource=credentialDesigns&rarea=issuer-designs
Reference: Issuer Branding
Also used from issuer instance configuration: Issuer tenant config.

List and create​

Issuer Branding list

Create with alias, display name, and issuer DID (or product-equivalent binding). Finish localization and logos on the detail workbench.

New issuer branding

Detail​

Overview holds bindings and identity. Localization holds per-locale display strings. Attach render variants the same way as on credential designs when the issuer itself needs a branded card.

Issuer branding OverviewIssuer branding Localization

How the libraries fit together​

  1. Upload assets (logos, templates).
  2. Build render variants that reference those assets.
  3. Create issuer branding and attach variants if the authority needs its own card.
  4. Create credential designs (claims and format bindings), attach the same or different variants, and optionally link an issuer design.
  5. Point issuance templates and issuer settings at the design / configuration ids.

Changing a shared render variant or asset URI updates every design that still references it. Prefer cloning a variant when only one product line should change.

After designs​

  1. Status lists and revocation if credentials are revocable
  2. Issue credentials
  3. Confirm issuer credential_configurations_supported picks up configuration ids from design bindings

Next​