Migrating from 3.x to 4.0¶

This guide covers all breaking changes introduced in EUDIPLO v4.0 and the steps required to migrate from any 3.x version.

Back up before upgrading

Always back up your database before performing a major version upgrade.

Summary of Breaking Changes¶

Area	Change	Impact
API Prefix	All management endpoints now require `/api/` prefix	High
Key Management	`certId`/`keyId` replaced by unified `keyChainId`	High
Credential Configuration	`claimsWebhook` replaced by `attributeProviderId`	High
Notification Configuration	`notificationWebhook` replaced by `webhookEndpointId`	Medium
Configuration Import	Key/cert import directories merged into `key-chains/`	Medium
Dependency Packages	Migrated to @owf ecosystem packages	Low (SDK)

1. API Prefix Change¶

What Changed¶

All management API endpoints are now prefixed with /api/. This aligns with common REST conventions and simplifies reverse proxy configuration.

Migration Steps¶

Update all API client URLs:

Before (3.x)	After (4.0)
`GET /tenants`	`GET /api/tenants`
`POST /tenants/{id}/credentials`	`POST /api/tenants/{id}/credentials`
`GET /sessions/{id}`	`GET /api/sessions/{id}`
`GET /docs` (Swagger UI)	`GET /api/docs`
`GET /docs-json` (OpenAPI spec)	`GET /api/docs-json`

Protocol endpoints unchanged

OID4VCI and OID4VP protocol endpoints (e.g., /.well-known/openid-credential-issuer, /authorize, /token, /credential) are not affected. Only management/admin endpoints have the new prefix.

Code Examples¶

Before (3.x):

const response = await fetch('https://eudiplo.example.com/tenants');

After (4.0):

const response = await fetch('https://eudiplo.example.com/api/tenants');

Root Endpoint¶

The GET / endpoint no longer returns version information. Use GET /api/health or check the X-EUDIPLO-Version response header instead.

2. Unified Key Chain Model¶

What Changed¶

The separate Key and Certificate entities have been unified into a single KeyChain entity. This simplifies key management by treating a key and its associated certificate(s) as a single unit.

Field renames:

Before (3.x)	After (4.0)
`keyId`	`keyChainId`
`certId`	`keyChainId`

Migration Steps¶

API Requests/Responses¶

Update all references in your integration code:

Before (3.x):

{
    "keyId": "issuer-key-1",
    "certId": "issuer-cert-1"
}

After (4.0):

{
    "keyChainId": "issuer-keychain-1"
}

Configuration Import Directory¶

If you use the configuration import feature (CONFIG_IMPORT_DIR), restructure your import directory:

Before (3.x):

config/
├── keys/
│   └── issuer-key.json
├── certs/
│   └── issuer-cert.json
└── credentials/
    └── pid.json

After (4.0):

config/
├── key-chains/
│   └── issuer-keychain.json
└── credentials/
    └── pid.json

Key Chain Configuration Format¶

Before (3.x) — Separate files:

keys/issuer-key.json

{
    "id": "issuer-key-1",
    "algorithm": "ES256",
    "privateKeyPem": "-----BEGIN PRIVATE KEY-----\n..."
}

certs/issuer-cert.json

{
    "id": "issuer-cert-1",
    "keyId": "issuer-key-1",
    "certificatePem": "-----BEGIN CERTIFICATE-----\n..."
}

After (4.0) — Combined file:

key-chains/issuer-keychain.json

{
    "id": "issuer-keychain-1",
    "algorithm": "ES256",
    "privateKeyPem": "-----BEGIN PRIVATE KEY-----\n...",
    "certificateChainPem": ["-----BEGIN CERTIFICATE-----\n..."]
}

Database Migration¶

The database migration runs automatically on startup and:

Creates the new key_chain table
Migrates existing keys and certificates into unified key chains
Updates all foreign key references in credential configurations

No manual database changes are required.

3. Attribute Providers (replaces Claims Webhook)¶

What Changed¶

The inline claimsWebhook configuration in credential configs has been replaced by a reference to an Attribute Provider entity. This allows:

Reusing the same attribute source across multiple credentials
Centralized management of external data sources
Support for different attribute provider types (webhook, database, etc.)

Migration Steps¶

Step 1: Create Attribute Providers¶

For each unique claimsWebhook URL in your credential configurations, create an Attribute Provider:

curl -X POST https://eudiplo.example.com/api/tenants/{tenantId}/attribute-providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Claims Service",
    "type": "webhook",
    "config": {
      "url": "https://claims.example.com/user-claims",
      "headers": {
        "Authorization": "Bearer ${env:CLAIMS_API_KEY}"
      }
    }
  }'

Note the returned id for use in credential configurations.

Step 2: Update Credential Configurations¶

Replace claimsWebhook with attributeProviderId:

Before (3.x):

{
    "type": "PersonIdentificationData",
    "claimsWebhook": {
        "url": "https://claims.example.com/user-claims",
        "headers": {
            "Authorization": "Bearer secret"
        }
    }
}

After (4.0):

{
    "type": "PersonIdentificationData",
    "attributeProviderId": "ap_abc123"
}

Database Migration¶

The automatic migration will:

Create the attribute_provider table
Extract unique webhook configurations into Attribute Provider entities
Replace claimsWebhook references with attributeProviderId foreign keys

Review migrated providers

After upgrading, review the auto-created Attribute Providers in the UI or via API. You may want to rename them for clarity.

4. Webhook Endpoints (replaces Notification Webhook)¶

What Changed¶

Similar to Attribute Providers, the inline notificationWebhook configuration has been replaced by a reference to a Webhook Endpoint entity.

Migration Steps¶

Step 1: Create Webhook Endpoints¶

curl -X POST https://eudiplo.example.com/api/tenants/{tenantId}/webhook-endpoints \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Issuance Notifications",
    "url": "https://webhook.example.com/eudiplo-events",
    "events": ["credential.issued", "credential.revoked"],
    "headers": {
      "X-Webhook-Secret": "${env:WEBHOOK_SECRET}"
    }
  }'

Step 2: Update Credential Configurations¶

Replace notificationWebhook with webhookEndpointId:

Before (3.x):

{
    "type": "PersonIdentificationData",
    "notificationWebhook": {
        "url": "https://webhook.example.com/notify"
    }
}

After (4.0):

{
    "type": "PersonIdentificationData",
    "webhookEndpointId": "we_xyz789"
}

Database Migration¶

Handled automatically — existing webhook configurations are extracted into Webhook Endpoint entities.

5. Package Dependencies (@owf Ecosystem)¶

What Changed¶

EUDIPLO now uses packages from the OpenWallet Foundation ecosystem:

Before (3.x)	After (4.0)
`@sd-jwt/jwt-status-list`	`@owf/token-status-list`
`@animo-id/mdoc`	`@owf/mdoc`
Internal LoTE	`@owf/eudi-lote`

Impact¶

For EUDIPLO users: No action required. This is an internal dependency change.
For SDK users: If you use @eudiplo/sdk-core directly and import status list utilities, update your imports:

Before (3.x):

import { StatusList } from '@sd-jwt/jwt-status-list';

After (4.0):

import { StatusList } from '@owf/token-status-list';

6. New Features in v4.0¶

While not breaking changes, the following new features are available after upgrading:

AWS KMS Adapter¶

Use AWS Key Management Service for key storage:

KEY_STORAGE_TYPE=aws-kms
AWS_KMS_REGION=eu-central-1

See Key Management for full configuration.

Session Log Storage¶

Store detailed session logs for debugging and audit:

LOG_SESSION_STORE=true
LOG_SESSION_RETENTION_DAYS=30

Logs are stored in the database and accessible via the Sessions API.

Migration Checklist¶

Use this checklist to track your migration progress:

Troubleshooting¶

"404 Not Found" on API calls¶

Cause: Missing /api/ prefix on management endpoints.

Solution: Prepend /api/ to all management API URLs.

"Invalid keyChainId" error¶

Cause: Using old keyId or certId field names.

Solution: Replace with keyChainId in your request body.

"attributeProviderId is required"¶

Cause: Credential config still uses claimsWebhook format.

Solution: Create an Attribute Provider and reference it by ID.

Key import fails after upgrade¶

Cause: Keys are still in the old keys/ directory.

Solution: Move key files to key-chains/ and update to the combined format.

Need Help?¶

Open an issue for migration problems
Join the discussion for questions
Check the Architecture docs for detailed explanations