Skip to Content
API and DashboardCredential Metadata

Credential Metadata

Paradym automatically generates and hosts credential metadata so wallets, verifiers, and developers can understand how to display and validate credentials. This page describes the two types of metadata that Paradym manages for credential templates.

OpenID4VCI Issuer Metadata

When issuing credentials via the OpenID4VCI protocol, Paradym exposes an OpenID4VCI Credential Issuer Metadata document at the well-known endpoint:

GET {issuer}/.well-known/openid-credential-issuer

This document is automatically generated and updated by Paradym for every active credential template in your project. Wallets retrieve this document during the issuance flow to learn how to display and request each credential type.

The issuer metadata contains:

  • Credential configurations — one entry per template, describing the credential format, type, and cryptographic binding requirements.
  • Display metadata — name, background color, background image, logo, and text color for each locale.
  • Claim display metadata — human-readable labels and descriptions for each claim per locale.

Localization settings you configure on your credential templates are automatically reflected in the issuer metadata. See the Localization guide for details on configuring display names and descriptions in multiple languages.

SD-JWT VC Type Metadata

The SD-JWT VC specification  defines a Type Metadata document tied to the vct (Verifiable Credential Type) URL. Wallets and verifiers can dereference the vct URL to retrieve a JSON document that describes the credential type’s display and claim structure.

The Type Metadata document contains:

  • vct — the canonical type identifier (matches the vct URL).
  • name / description — human-readable information for developers.
  • display — localised names, descriptions, and branding (logo, background color/image) for wallets to render the credential.
  • claims — per-claim metadata including display labels, mandatory flag, and selective-disclosure hints.

Localization data from your credential template flows into the display array and each claim’s display array. See the Localization guide for details.

Updating a template changes the type metadata. Wallets and verifiers may fetch the document on demand. Breaking changes — such as removing required claims or changing selective-disclosure rules — can cause previously issued credentials to fail type-metadata validation. If you need to make breaking changes, create a new template instead.

Automatic hosting by Paradym

When you create or update an SD-JWT VC credential template with a Paradym-generated vct URL (e.g. https://metadata.paradym.id/types/<id>), Paradym automatically:

  1. Generates the Type Metadata document from the template’s configuration (name, description, branding, attributes, and localization).
  2. Uploads it to the public metadata bucket and serves it at the vct URL.

The document is updated every time the template is saved, so wallets and verifiers always see up-to-date metadata.

Using a custom vct

If you supply your own vct when creating a template, Paradym does not publish the Type Metadata document. You are responsible for making it available to wallets and verifiers. How you do that depends on the kind of vct you use.

Retrieving the document from Paradym

You can download the Paradym-generated Type Metadata document for any SD-JWT VC template — regardless of whether the vct URL is Paradym-hosted or custom — using the dedicated API endpoint:

GET /v1/projects/{projectId}/templates/credentials/sd-jwt-vc/{credentialTemplateId}/type-metadata

Refer to the API Reference  for full details.

You can also copy the document directly from the Type Metadata section on the template detail page in the dashboard (this section only appears for custom vct values).

Hosting an HTTPS vct URL

When your vct is an HTTPS URL (e.g. https://example.com/credentials/loyalty-card), wallets and verifiers dereference it directly. Host the document at the exact URL you configured as the vct value. The server must:

  • Respond to GET requests with an HTTP 200 status.
  • Return the document as application/json.
  • Be reachable over HTTPS.

Non-resolvable vct values

A vct does not have to be an HTTPS URL — it only has to be a URI . Some ecosystems use URNs or other non-https identifiers, for example urn:eudi:pid:1.

These values are not globally resolvable: a wallet or verifier cannot simply dereference them over the network to fetch the Type Metadata. Instead, the document is retrieved using an ecosystem-specific method (for example a trusted registry, a pre-provisioned catalogue, or out-of-band distribution defined by that ecosystem).

You can still use the Paradym-generated Type Metadata document for these credential types — retrieve it from the API or the dashboard as described above — but how the document is published and resolved is not defined by Paradym and depends entirely on the rules of the ecosystem you are participating in.

When the template is updated and you want the type metadata to stay in sync, re-download the document from the API or dashboard and re-publish it (or re-distribute it through your ecosystem’s mechanism).

Last updated on
LocalizationGlossary