Skip to main content

Connector architecture

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

Your organization acts as the Relying Party (RP). You own the registration with member state authorities, manage your certificates, and control all data processing. The connector handles protocol implementation, verification, 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 to retrieve authorization requests and submit presentation responses. This interface is exposed to the internet.
  • Internal management interface: Provides the API your systems use to create presentation requests. 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 three components:

Management API​

A protected API on the internal interface that your systems use to operate the connector. Through this API you create presentation requests that define which credentials to request from the wallet and how to structure the verification flow.

Public OID4VP endpoints​

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

Verification engine​

The core logic that processes incoming credentials. The connector delegates credential parsing and validation to a dedicated internal verification service. From your perspective this is a single logical component, but operationally it runs as a separate process. 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).

Session storage​

The connector maintains temporary session data for each active presentation request. Sessions track the state of an ongoing verification flow, from request creation through wallet interaction to result delivery.

Sessions are automatically cleaned up after they complete or expire. 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 to share data. The connector uses a callback-based event model to handle this flow.

Callback delivery​

After verification completes, the connector delivers a Presented Credentials Event to your callback endpoint. This event contains the verification result and, for successful verifications, the verified credential data. See Presented Credentials Event statuses for the possible outcomes.

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.

  • Event-driven: Your system does not need to poll for results. The connector pushes the event to your callback endpoint.
  • No persistence: Verified data is sent to your callback and then deleted from the connector.
  • 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.
  • Wallet impact: Because delivery is synchronous, a slow or failing callback handler causes the wallet to receive an error response. Design your callback handler to respond quickly.

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. 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 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. Verified credentials are processed in memory, delivered to your callback, and then deleted. You cannot retrieve historical verification results from the connector. This design minimizes the attack surface by ensuring sensitive identity data does not accumulate in storage.

Further reading​

  • OID4VP protocol—how the connector implements the OpenID for Verifiable Presentations standard
  • The ephemeral data model—how the connector processes credentials without persistent storage
  • Certificates in EUDI—how X.509 certificates establish Relying Party identity in the EUDI Wallet ecosystem