Skip to main content

Getting started

Get up and running with the Truvity EUDIW Connector in minutes. This guide walks you through the credential verification flow and helps you create your first presentation request.

How it works​

A credential verification flow involves five steps:

  1. Your backend creates a presentation request. You call POST /oidc4vp on the internal management API (port 8081) with a DCQL query specifying the credentials and attributes you need. The connector returns a state value for correlation, a same_device_request_uri for deep links, and a cross_device_request_uri for QR codes.

  2. You display the request URI to the user. For cross-device flows, render the cross_device_request_uri as a QR code. For same-device flows, redirect the user to the same_device_request_uri deep link.

  3. The wallet retrieves and displays the request. The EUDI Wallet fetches the signed authorization request from the connector's public protocol endpoint, verifies your X.509 certificate, and displays a consent screen to the user.

  4. The user approves and the wallet submits the presentation. The user consents with biometric authentication. The wallet encrypts the presentation and submits it to the connector's public protocol endpoint using the direct_post.jwt response mode.

  5. The connector verifies credentials and delivers the result. The connector decrypts, verifies signatures, checks revocation, and delivers a PresentedCredentialsEvent to your callback endpoint.

The connector implements OID4VP under the High Assurance Interoperability Profile (HAIP), which defines the required algorithms, response modes, and credential formats for the EUDI Wallet ecosystem. You don't need to configure these protocol options. The connector applies HAIP-compliant settings by default.

Prerequisites​

Before you begin
  • Access to a Truvity EUDIW Connector instance. The connector is not publicly available—contact Truvity at hello@truvity.com to get access.
  • A running connector instance with its public base URL configured and a callback URL pointing to your backend endpoint (for example, http://localhost:3000/callback/kyc). See connector architecture for the deployment model and how callbacks are delivered.
  • An X.509 access certificate configured in the connector. See Manage certificates to generate test certificates or import production ones.
  • A callback endpoint reachable from the connector over internal networking. The connector delivers verification results to this endpoint.
  • Access to the internal management API on port 8081.

First presentation request​

Call POST /oidc4vp on the management API with a DCQL query. This example requests a PID credential with basic identity attributes. The dc+sd-jwt format is the SD-JWT VC credential format used in the EUDI ecosystem.

note

The VCT values, requested claims, and credential values in this guide are examples. In production, request the attributes required by your use case and available in the target attestation scheme. Available attributes vary by issuer and member state.

curl -X POST http://connector:8081/oidc4vp \
  -H "Content-Type: application/json" \
  -d '{
    "dcql_query": {
      "credentials": [
        {
          "id": "pid",
          "format": "dc+sd-jwt",
          "meta": {
            "vct_values": ["urn:eudi:pid:1"]
          },
          "claims": [
            { "path": ["given_name"] },
            { "path": ["family_name"] },
            { "path": ["birthdate"] }
          ]
        }
      ]
    }
  }'

Example response:

{
  "state": "abc123",
  "same_device_request_uri": "openid4vp://?client_id=...&request_uri=https%3A%2F%2Fconnector.example.com%2Foidc4vp%2Fabc123%2Frequest%3Fflow_type%3Dsame-device",
  "cross_device_request_uri": "openid4vp://?client_id=...&request_uri=https%3A%2F%2Fconnector.example.com%2Foidc4vp%2Fabc123%2Frequest%3Fflow_type%3Dcross-device"
}

Store the state value to correlate with the callback later. Both URIs use the openid4vp:// scheme with client_id and request_uri query parameters — pass them to the wallet as-is without parsing. Render cross_device_request_uri as a QR code or redirect the user to same_device_request_uri for same-device flows.

The response contains:

  • state—a correlation token to match the callback with this request.
  • same_device_request_uri—an openid4vp:// URI for same-device flows. Pass the full URI to the wallet as a deep link.
  • cross_device_request_uri—an openid4vp:// URI to render as a QR code for cross-device flows.

Handle the callback​

Implement a callback endpoint that receives the PresentedCredentialsEvent from the connector. The event's status field indicates the verification outcome.

# Simulate a FULFILLED callback for testing
curl -X POST http://localhost:3000/callback \
  -H "Content-Type: application/json" \
  -d '{
    "status": "FULFILLED",
    "state": "abc123",
    "responseCode": "8k5CwzAseoGVK_bHQQJWMw",
    "credentials": {
      "pid": [
        {
          "issuer": "https://issuer.example.com",
          "claims": {
            "given_name": "Erika",
            "family_name": "Mustermann",
            "birthdate": "1964-08-12"
          },
          "signatureIsValid": true,
          "supportRevocation": false,
          "supportTrustAnchor": true,
          "isTrusted": false,
          "kbKeyId": "KrXxHnYsf-Inp0hW1M6r...",
          "kbSignatureIsValid": true
        }
      ]
    },
    "credentialsRaw": {
      "pid": [
        {
          "claims": "eyJiaXJ0aGRhdGUiOiIx...",
          "issuer": "https://issuer.example.com",
          "kbKeyId": "KrXxHnYsf-Inp0hW1M6r..."
        }
      ]
    }
  }'

The credentials and credentialsRaw fields may be absent for REJECTED, EXPIRED, and PROCESSING_ERROR statuses. The errorDetails field is present for REJECTED, PROCESSING_ERROR, and VERIFICATION_FAILED statuses. For same-device flows, the event includes a responseCode field to correlate the browser redirect with the callback.

For the complete list of statuses and error codes, see the callback events reference.

Data handling responsibility

You are responsible for applying your own data retention and access control policies to credential data received through callbacks. The connector does not persist credential data after delivering the callback.

Next steps​

Further reading​