Skip to main content

Connector architecture

The Truvity EUDIW Connector enables your organization to verify and issue credentials in the EUDI Wallet ecosystem. It abstracts the complexity of the OID4VP and OID4VCI protocols, cryptographic operations, and trust management, allowing your systems to request, verify, and issue digital credentials through a management API.

Your organization acts as the Relying Party (RP) for verification and as a credential issuer for issuance. You own the registration with member state authorities, manage your certificates, and control all data processing. The connector handles protocol implementation, credential verification and signing, and delivers results to your callback endpoint.

Network architecture​

The connector exposes two separate network interfaces with distinct security profiles:

  • Public-facing interface: Handles wallet protocol interactions. EUDI Wallets connect to these endpoints for verification (retrieving authorization requests and submitting presentation responses) and for issuance (discovering issuer metadata, requesting nonces, and obtaining credentials). This interface is exposed to the internet.
  • Internal management interface: Provides the API your systems use to create presentation requests and credential offers. This interface is accessible only within your internal network.

This separation ensures that wallet-facing protocol endpoints are isolated from your management operations, reducing the attack surface.

System components​

The connector consists of the following components, spanning both verification and issuance:

Management API​

A protected API on the internal interface that your systems use to operate the connector. Through this API you create presentation requests for verification and credential offers for issuance. The management API is the single integration point for both flows.

Public OID4VP endpoints​

Publicly accessible endpoints on the public-facing interface that EUDI Wallets interact with during verification. These handle the protocol handshake described in the OID4VP standard: the wallet retrieves the signed authorization request and submits the encrypted presentation response.

Public OID4VCI endpoints​

Publicly accessible endpoints on the public-facing interface that EUDI Wallets interact with during issuance. These handle the OID4VCI protocol flow: the wallet discovers credential issuer metadata, requests nonces, and submits credential requests. The connector serves metadata that describes its issuer capabilities and the credential types it supports.

Authorization server integration​

The connector integrates with an authorization server that manages the OAuth 2.0 token lifecycle during issuance. The authorization server owns the token endpoint and handles pre-authorized code management, DPoP validation (per RFC 9449), and transaction code validation. The wallet discovers the authorization server through its metadata endpoint and exchanges pre-authorized codes for sender-constrained access tokens.

Verification engine​

The core logic that processes incoming credentials during verification. The connector delegates credential parsing and validation to a dedicated verification component. From your perspective this is a single logical component. The verification engine performs:

  • Decryption: Using ephemeral keys generated for each individual request.
  • Protocol verification: Validating the OID4VP structure, nonce, and state.
  • Credential verification: Checking signatures, validity periods, and revocation status.
  • Device binding: Verifying that the wallet holder controls the credential (see Device binding).

Credential signing​

The core logic that produces credentials during issuance. When the wallet submits a valid credential request with a key proof, the connector signs the credential using the issuer signing certificate and returns it to the wallet. The signing component binds the credential to the wallet's key, ensuring only the intended holder can present it.

Session storage​

The connector maintains temporary session data for each active verification or issuance flow. Verification sessions track the state of a presentation request from creation through wallet interaction to result delivery. Issuance sessions track the state of a credential offer through the token exchange, credential request, and signing phases.

Sessions are automatically cleaned up after they complete or expire. For issuance, credential claims are purged from the session when the flow fails or the session expires. After successful issuance, claims persist until the session TTL expires to support repeated credential requests (per OID4VCI Section 14.3). Session expiry is detected lazily at request time. For details on the connector's data retention approach, see The ephemeral data model.

No user credential data persists in the connector beyond the lifetime of a session.

Data flow​

Interactions with EUDI Wallets are asynchronous. The user must open their wallet, authenticate, and consent. The connector uses a callback-based event model to handle both verification and issuance flows.

Verification data flow​

Issuance data flow​

The issuance flow follows the OID4VCI protocol using the pre-authorized code grant. Your backend creates a credential offer through the management API. The connector coordinates with the authorization server to generate a pre-authorized code and returns a credential offer URI that you display to the user. The wallet discovers the connector's issuer metadata and the authorization server metadata, exchanges the pre-authorized code for a sender-constrained access token using DPoP (RFC 9449), requests a nonce, and submits a credential request with a key proof. The connector signs the credential, delivers it to the wallet, and sends an issuance callback to your backend. Claims persist in the session until the session TTL expires, supporting repeated credential requests per OID4VCI Section 14.3.

Callback delivery​

The connector delivers callback events to your endpoint during both verification and issuance flows.

For verification, the connector delivers a Presented Credentials Event at the end of the presentation flow, containing the verification result and, for successful verifications, the verified credential data. See Presented Credentials Event statuses for the possible outcomes.

For issuance, the connector delivers Issuance Events at multiple points during the flow. An OFFER_CREATED event confirms the offer was created and the session is active. Terminal events indicate the final outcome: ISSUED (credential successfully delivered to the wallet), FAILED (issuance failed, with error details describing the reason), or EXPIRED (the session expired before the wallet completed the flow). See Issuance Event statuses for details.

For verification, callback delivery is synchronous with the wallet response. The connector delivers the callback before responding to the wallet. If callback delivery fails after all retry attempts, the connector returns an error to the wallet. This means a slow or failing callback handler causes the wallet to receive an error response—design your verification callback handler to respond quickly.

For issuance, callback delivery is fire-and-forget. The connector sends the callback but does not block the wallet interaction on delivery success. If callback delivery fails, the error is logged but the issuance flow continues normally.

  • Event-driven: Your system does not need to poll for results. The connector pushes events to your callback endpoint for both verification and issuance flows.
  • No persistence: For verification, credential data is sent to your callback and then deleted from the connector. For issuance, credential data is delivered to the wallet and the session expires after its TTL; the callback contains only status metadata.
  • Retry behavior: The connector retries delivery on network errors and server errors (HTTP 5xx). It does not retry on client errors (HTTP 4xx). The default is one retry with a two-second timeout per attempt.

Transactional data​

You can optionally include transactional data when creating a presentation request. Transactional data is contextual information included in the request that the wallet displays to the user during the consent step. After the user approves, the wallet cryptographically signs the transactional data through the device binding mechanism and returns hashes that the Relying Party verifies. This two-step process—request-side inclusion followed by wallet-side signing—provides cryptographic proof that the user approved the specific context. It enables use cases where the user needs to see and explicitly authorize what they are agreeing to (for example, a payment amount or document reference).

Security architecture​

The connector implements several security mechanisms aligned with the Architecture Reference Framework (ARF).

Identity and trust​

To interact with wallets, the connector must establish a trusted identity using X.509 certificates.

For verification, you obtain access certificates from a Certificate Authority (CA) or member state registrar and configure them in the connector at deployment time. Certificate rotation requires updating the deployment configuration and restarting the connector. Every authorization request is signed with the private key associated with your certificate, allowing the wallet to verify your identity before showing the consent screen.

For issuance, the connector uses two additional certificate types. The issuer signing certificate signs the credentials delivered to wallets and is included in the credential header so that wallets and other Relying Parties can verify the credential's authenticity. The access certificate for issuance signs the credential issuer metadata, proving the connector's participation in the ecosystem. These certificates use separate keys from each other and from the verification access certificate. For details, see Certificates in EUDI.

Ephemeral encryption​

The connector generates a unique encryption key pair for each presentation request. The public key is included in the authorization request sent to the wallet, and the wallet uses it to encrypt the presentation response. The connector decrypts the response using the corresponding private key. After verification completes and the callback is delivered, the ephemeral keys are permanently deleted. For details, see Encryption key management.

Privacy by design​

The connector follows an ephemeral data model as a security architecture choice. For verification, credentials are processed in memory, delivered to your callback, and then deleted. For issuance, claim data provided in the credential offer is purged from the session when the flow fails, and the session itself expires after its TTL—at which point all remaining data is deleted. You cannot retrieve historical verification or issuance results from the connector. This design minimizes the attack surface by ensuring sensitive identity data does not accumulate in storage.

Further reading​