Skip to main content

Changelog

All notable changes to the iDen2 APIs are documented here.

The format follows Keep a Changelog, and the APIs adhere to Semantic Versioning. Entries are grouped per release under Breaking Changes, New Features, Bug Fixes, and Deprecations.

[Unreleased]​

Breaking Changes​

  • Credential Factory behaviour changed on 2026-10-20 (now live); the docs are updated to match:
    • Wallet Offer Response: the wallet can respond while the offer is pending or after the credential is claimed. accepted sets status accepted (an offer accepted before issuance stays accepted and gains the issuance record); rejected sets status rejected with failureReason wallet_rejected (previously revoked). Repeating the same answer returns 200; a different answer after the offer was settled returns 409.
    • Revoke Credential: action suspend returns 501 — credentials are registered on a revocation status list only. 409 now means the credential is already revoked.
    • Get Offer Status: credentialId is the credential's registry ID (urn:uuid: form), the same value as credentialStatus.credentialId and the ID Revoke Credential takes. failureReason is also set on rejected and expired offers.
    • Create Credential Offer: a negative offerTtlSeconds returns 400, and credentialData must be a non-empty object.
    • An offer that expires unclaimed has its registry entry revoked.
    • An offer can be accepted before its credential is issued, so treat it as successful only once claimedAt/credentialId are present; the polling guidance is updated.
    • After a revoke, a revocation webhook ("event": "revocation") is sent. It carries credentialId, not externalId or offerId, and isn't counted in callbackAttempts/callbackDeliveryStatus. An expired offer now also has failedAt.

Documentation​

  • Using externalId for Correlation: Credential Factory's issuance_completed webhook carries your externalId value as userId; issuance_failed, wallet_accepted and wallet_rejected carry externalId; revocation carries neither (match on credentialId).
  • Updated the docs site to the new iDen2 brand: new logo (with a dark-mode variant), favicon and link-preview (social card) image, and the purple palette with purple-800 as the primary colour.
  • Renamed the services in the docs: IaaS (Issuer as a Service) is now Credential Factory, and VaaS (Verification as a Service) is now Verification Gateway. Only the names changed — hostnames, API paths and request/response shapes are the same. The API intro pages moved to /docs/api-reference/iaas/credential-factory-api and /docs/api-reference/vaas/verification-gateway-api; the old addresses redirect.
  • Enabled Dart syntax highlighting for Wallet SDK code snippets.
  • Added the Wallet SDK developer guide (early access) covering the embeddable Flutter wallet SDK: Overview, Getting Started, Configuration, Authentication, Credential Storage, Credential Issuance, Credential Presentation, Deep Links, Prompts, Trust Network, Error Handling, and a full API Reference. Updated the Mobile Wallet & Wallet API guide to link the SDK docs (previously "coming soon").
  • Added Network Credential Registry, Trust Network API, and Mobile Wallet & Wallet API guides.
  • Added Credential Registry concept and Credential Registry Architecture pages, and wove the Trust Network and Credential Registry checks into the issuance and verification flow diagrams.
  • Aligned Credential Factory examples with shipped credential configuration IDs (VerifiedPerson_vc+sd-jwt).
  • Documented Verification Gateway JAR flow: GET /openid4vc/request/{sessionId} and GET /.well-known/jwks.json.
  • Switched all server-to-server authentication documentation to OAuth 2.0 client_credentials Bearer tokens; removed HTTP Basic Authentication, which is not available to external integrators.
  • Corrected the credential revocation request body to { "action": "revoke", "reason": "..." } (was reasonCode).
  • Clarified that vc+sd-jwt credentials are selectively disclosable by default; selectiveDisclosure is opt-in to restrict.
  • Clarified callbackDeliveryStatus vs failureReason for webhook delivery failures.
  • Added Credential Factory offer statuses: accepted, rejected, suspended.
  • Added Verification Gateway failureReason: audience_mismatch; removed incorrect callback_exhausted from verification failure enum.

Bug Fixes (spec corrections)​

  • OpenAPI: failureReason enum now matches go-monorepo implementation.
  • OpenAPI: added callbackDeliveryStatus field on verification sessions.
  • Credential Factory: documented the current offer paths POST /api/v1/iaas/credential-offers and GET /api/v1/iaas/credential-offers/{offerId}, and updated every guide to use them. The old /api/v1/issuer/offers paths still work but are marked deprecated.
  • Credential Factory: Wallet Offer Response now documents the required token query parameter. POST to the walletResponseUrl returned at offer creation, unchanged; a call without the token returns 404.
  • Credential Factory: Revoke Credential now matches the API: required action, optional reason, credentialId in urn:uuid: form, 204 No Content on success, and 400/401/403/404/409/500/503 errors.
  • Credential Factory: authenticationMethod is optional on offer creation (defaults to PRE_AUTHORIZED). Documented the audience field (an array with one Network Member URN — the guide example was a plain string), the externalId 255-character limit, selectiveDisclosure.fields limits, TTL defaulting and capping, and that unknown request fields are rejected.
  • Credential Factory: added walletResponseUrl and credentialId to the created offer, and credentialId, credentialStatus, respondedAt, acceptedAt, rejectedAt, revokedAt, failedAt, failureReason, failureDescription, updatedAt, callbackAttempts and callbackDeliveryStatus to offer status.
  • Credential Factory: Get Offer Status returns 200 with status expired for an expired offer, not 410, and documents 403 (missing scope). Create Credential Offer documents 501 (unsupported credential format). Added the Problem objectPath field.
  • Credential Factory: corrected the offer state descriptions — accepted means the holder accepted the credential (not "claim in progress"), and revoked results from your own revoke call or from a failed offer; the polling guide now stops when the credential is issued or the offer ends, so an accepted offer is no longer treated as expired.

[1.0.0] — 2026-06-12​

Initial public release of the iDen2 API services.

Breaking Changes​

  • None — initial release.

New Features​

  • Credential Factory (then IaaS — Issuer as a Service) (iaas.stg.iden2.app, API v1)
    • POST /api/v1/issuer/offers — create OID4VCI credential offers with pre-authorized code flow, SD-JWT selective disclosure configuration, externalId correlation, and configurable TTL. Returns offerUrl and a pre-rendered qrCodeDataUrl.
    • GET /api/v1/issuer/offers/{offerId} — poll offer status (pending / claimed / expired / revoked), including holderBinding and claimedAt on claim.
    • POST /api/v1/issuer/credentials/{credentialId}/revoke — revoke an issued credential (configuration-dependent).
    • Wallet API: POST /api/v1/wallet/offers/{offerId}/response — holder wallet acceptance/rejection signal.
  • Verification Gateway (then VaaS — Verification as a Service) (vaas.stg.iden2.app, API v1)
    • POST /api/v1/verifier/sessions — create OpenID4VP verification sessions. Returns authorizationUrl (with trust network client_metadata) and a pre-rendered qrCodeDataUrl.
    • GET /api/v1/verifier/sessions/{sessionId} — poll session status and results, including extracted credentialData, detailed verificationResult checks, lifecycle timestamps, callbackDeliveryStatus, and failureReason diagnostics.
    • Wallet API: GET /openid4vc/pd/{state} (legacy presentation definition), GET /openid4vc/request/{sessionId} (JAR Request Object), POST /openid4vc/verify/{state} (VP token submission), GET /.well-known/jwks.json (JAR signature verification).
  • RFC 9457 Problem Details error model across all endpoints, including subproblems for compound validation errors.
  • Webhook callbacks on session completion (account-configured), with callbackDeliveredAt / callbackAttempts / callbackDeliveryStatus delivery telemetry.

Bug Fixes​

  • None — initial release.

Deprecations​

  • None.