Skip to main content

Configure credential types

This guide shows you how to configure Type Metadata for the Truvity EUDIW Connector. Type Metadata defines the credential types your connector can issue—including claim definitions, selective disclosure settings, display metadata, and the Verifiable Credential Type (VCT) URI that wallets use to identify the credential type.

Prerequisites
  • A running connector instance, or one you are preparing to deploy. See connector architecture for the deployment model.
  • Access to the connector's configuration files
  • Understanding of the credential type you want to issue (claim structure, Verifiable Credential Type URI)

Overview​

Type Metadata is a JSON document that describes a credential type. It tells the connector which claims to include in a credential and what display information to present to wallets. The connector loads Type Metadata from its configuration at startup and serves it at a public endpoint (/oidc4vci/types/{credential_configuration_id}) so wallets can discover supported credential types.

Type Metadata feeds into the connector's Credential Issuer Metadata—the credential_configurations_supported map that wallets read from GET /.well-known/openid-credential-issuer. Each entry in that map corresponds to a configured credential configuration. When you create a credential offer, the credential_configuration_id must match a key in this map.

Time to implement: 30 minutes.

Step 1: Define Type Metadata​

Create a Type Metadata JSON document for your credential type. The example below defines an Account Ownership Credential (AOC) with bank account claims and selective disclosure settings.

{
  "name": "Account Ownership Credential",
  "vct": "https://issuer.example.com/oidc4vci/types/AccountOwnershipCredential",
  "claims": {
    "bankName": {
      "sd": "allowed",
      "display": { "name": "Bank name" }
    },
    "accountHolder": {
      "sd": "allowed",
      "display": { "name": "Account holder" }
    },
    "accountNumber": {
      "sd": "allowed",
      "display": { "name": "Account number" }
    },
    "iban": {
      "sd": "allowed",
      "display": { "name": "IBAN" }
    },
    "bic": {
      "sd": "allowed",
      "display": { "name": "BIC" }
    },
    "currency": {
      "sd": "allowed",
      "display": { "name": "Currency" }
    },
    "accountType": {
      "sd": "allowed",
      "display": { "name": "Account type" }
    }
  }
}

Key fields:

  • name—a human-readable display name for the credential type. The connector uses this in the Credential Issuer Metadata display array.
  • vct—a VCT URI placeholder. When vct.source is local, the connector rewrites this field to {base_url}/oidc4vci/types/{credential_configuration_id} at startup, making the Type Metadata available at a publicly resolvable URL. You can set any value here—the connector overrides it.
  • claims—defines each claim the credential contains. Set "sd": "allowed" for claims that support selective disclosure, allowing the wallet holder to choose whether to reveal them during presentation. The display object provides a human-readable name for the claim.
note

When vct.source is local, the connector automatically generates the public VCT URL from its base_url and the credential configuration ID. You don't need to configure a separate VCT hosting endpoint. When vct.source is external, you provide the URL directly and are responsible for hosting the Type Metadata at that URL.

Step 2: Load Type Metadata into the connector​

The connector loads Type Metadata from its configuration at startup. Each credential configuration references a Type Metadata JSON file via the credential_configurations configuration section.

# Configure a credential type with a local Type Metadata file
export CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_VCT_SOURCE=local
export CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_VCT_FILEPATH=/config/type-metadata/aoc.json
export CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_SCOPE=aoc_credential

Each credential configuration requires:

  • vct.source—how the Type Metadata is loaded. Use local for a file on disk (the connector serves it at {base_url}/oidc4vci/types/{config_id}), or external for a URL that wallets resolve directly.
  • vct.filepath—path to the Type Metadata JSON file (required when source is local).
  • vct.url—the external VCT URL (required when source is external). You are responsible for hosting the Type Metadata at this URL.
  • scope—the OAuth 2.0 scope associated with this credential type.

The credential configuration key (for example, AccountOwnershipCredential in CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_*) becomes the credential_configuration_id you pass when creating offers. The environment variable uses an uppercase representation of the key, but the actual credential_configuration_id preserves the original casing.

For Kubernetes deployments, store Type Metadata as a ConfigMap and mount it into the connector pod:

spec:
  containers:
    - name: connector
      env:
        - name: CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_VCT_SOURCE
          value: local
        - name: CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_VCT_FILEPATH
          value: /config/type-metadata/aoc.json
        - name: CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_SCOPE
          value: aoc_credential
      volumeMounts:
        - name: type-metadata
          mountPath: /config/type-metadata/
          readOnly: true
  volumes:
    - name: type-metadata
      configMap:
        name: connector-type-metadata

The connector serves the loaded Type Metadata at a public endpoint. Wallets discover available credential types through the Credential Issuer Metadata endpoint.

Step 3: Verify the configuration​

After starting the connector with your Type Metadata, verify that the credential type appears in the Credential Issuer Metadata.

curl -s https://connector.example.com/.well-known/openid-credential-issuer | jq .

The response should include your credential type in the credential_configurations_supported map:

{
  "credential_issuer": "https://connector.example.com",
  "authorization_servers": ["https://auth.example.com"],
  "credential_endpoint": "https://connector.example.com/oidc4vci/credential",
  "nonce_endpoint": "https://connector.example.com/oidc4vci/nonce",
  "credential_configurations_supported": {
    "AccountOwnershipCredential": {
      "format": "dc+sd-jwt",
      "scope": "aoc_credential",
      "vct": "https://connector.example.com/oidc4vci/types/AccountOwnershipCredential",
      "cryptographic_binding_methods_supported": ["jwk"],
      "credential_signing_alg_values_supported": ["ES256"],
      "proof_types_supported": {
        "jwt": {
          "proof_signing_alg_values_supported": ["ES256"]
        }
      },
      "display": [
        {
          "name": "Account Ownership Credential"
        }
      ]
    }
  },
  "signed_metadata": "<JWS signed with access certificate private key>"
}

Confirm that:

  1. Your credential configuration key (for example, AccountOwnershipCredential) appears as a key in credential_configurations_supported.
  2. The vct value matches {base_url}/oidc4vci/types/{credential_configuration_id} (for local source) or your external URL.
  3. The display field reflects the name from your Type Metadata document.
  4. The scope field matches the scope you configured.

Testing​

Test checklist​

  • Credential Issuer Metadata endpoint (GET /.well-known/openid-credential-issuer) returns a response
  • credential_configurations_supported contains your credential configuration key
  • The vct field is {base_url}/oidc4vci/types/{credential_configuration_id} (for local source)
  • The format field is dc+sd-jwt
  • The scope field matches your configured scope
  • The display field includes your credential type name
  • proof_types_supported includes jwt with ES256
  • cryptographic_binding_methods_supported includes jwk
  • The Type Metadata endpoint (GET /oidc4vci/types/{credential_configuration_id}) returns your JSON document
  • Creating a credential offer with the configured credential_configuration_id succeeds

Troubleshooting​

unknown_credential_configuration error when creating an offer​

The credential_configuration_id in your offer request doesn't match any configured credential type. Verify that:

  1. The credential configuration key in your environment variables matches the credential_configuration_id you use in the offer request (for example, CONNECTOR_CREDENTIAL_CONFIGURATIONS_ACCOUNTOWNERSHIPCREDENTIAL_* maps to credential_configuration_id: "AccountOwnershipCredential").
  2. The Type Metadata path in CONNECTOR_CREDENTIAL_CONFIGURATIONS_<ID>_VCT_FILEPATH points to a valid JSON file.
  3. The connector restarted after you added or modified credential configuration environment variables.

VCT URI not publicly resolvable​

Wallets fetch the vct URI to retrieve credential type metadata. When using vct.source=local, the connector serves the Type Metadata at {base_url}/oidc4vci/types/{credential_configuration_id}—ensure your base_url is publicly reachable. When using vct.source=external:

  1. Verify the URI is accessible from the public internet (not just your internal network).
  2. Check that the domain has valid DNS records and TLS certificates.
  3. Ensure no firewall rules block external access to the URI.

Missing required fields in Type Metadata​

The connector validates Type Metadata at startup. If the connector fails to start after adding a Type Metadata file, check the logs for validation errors. Common issues:

  • Missing or unreadable file—the path in CONNECTOR_CREDENTIAL_CONFIGURATIONS_<ID>_VCT_FILEPATH must point to a valid JSON file.
  • Invalid JSON—the file must be valid JSON that can be parsed.
  • Missing vct.source—each credential configuration must specify either local or external as the source type.
  • Missing vct.filepath—required when vct.source is local.

Next steps​

Further reading​