Skip to main content

Verifiable Credentials Architecture

This page shows how the pieces of the iDen2 platform fit together across the full credential lifecycle — from issuance through presentation to verification. For the conceptual model, see Verifiable Credentials Overview.

System landscape​

The hostnames keep the services' original identifiers: iaas for Credential Factory (formerly IaaS) and vaas for Verification Gateway (formerly VaaS).

Three trust boundaries matter:

  • Your backend ↔ iDen2 — authenticated server-to-server REST over HTTPS with OAuth 2.0 Bearer tokens. This is the only surface you implement.
  • Wallet ↔ iDen2 — the standards-based protocol surface (OID4VCI / OpenID4VP). Public, state-scoped, handled entirely by iDen2 and the wallet.
  • Inside iDen2 — both services consult two platform components: the Trust Network to anchor issuer and verifier identities, and the Credential Registry to register status at issuance and check revocation/suspension at verification.

End-to-end issuance flow (OID4VCI)​

Key points:

  • The offerUrl drives the holder flow entirely — your system only needs to display it.
  • Use qrCodeDataUrl to render the QR directly without an external library; it is a data:image/png;base64,... string.
  • Poll GET /offers/{offerId} at a reasonable interval (recommended: every 3–5 seconds) until the credential is issued (claimedAt is present, with status claimed or accepted) or the offer ends (rejected, expired or revoked).
  • If status is expired, create a new offer. Do not retry the same offerId.

End-to-end verification flow (OpenID4VP)​

Timestamp anatomy of a verification session​

The VerificationSession resource records each milestone, which you can use to diagnose latency, debug webhook delivery, and build SLA monitoring:

Session created:                createdAt
                                    │
Holder scans QR:                    │
Wallet submits VP:              vpReceivedAt
                                    │
Platform verification done:     vendorVerifiedAt
                                    │
Your webhook called:            callbackDeliveredAt
                                    │
Session expires:                expiresAt

Design properties worth knowing​

  • Stateless for you — iDen2 holds all protocol state, keyed by offerId / sessionId. Correlate to your own records with externalId instead of persisting iDen2's UUIDs as primary keys.
  • Tenancy isolation — issuers can only read their own offers; verifiers their own sessions. Cross-tenant lookups return 404.
  • Short-lived artifacts — offers and sessions are TTL-bounded. Expired ones are gone (410); always create fresh ones.

Where to go next​