Events monitoring 

Why event monitoring matters for an Issuer?

An issuer is not directly involved in the user-facing Relying Party integration, but it may need visibility into how authentication requests involving issued digital credentials are initiated, completed, rejected, or failed.

Event monitoring allows the issuer to answer questions such as:

• Which relying parties are using digital credentials issued by the issuer?
• How many authentication journeys are initiated per Relying Party?
• How many journeys are successfully completed?
• How many request cards were declined by users?
• How many requests expire due to timeout?
• How many requests fail because of technical issues?
• At which stage do users most often abandon the journey?
• Are specific relying parties generating unusually high failure or timeout rates?

This information enables the issuer to monitor usage, supports the identification of integration issues, and enables analysis of user interactions as well as operational support for relying parties.

Event progression during Online Authentication

The Online Authentication journey can be monitored as a progression of events. Each event represents a meaningful step in the authentication process.

Authentication request initiated and QR code displayed — AuthenticationRequested

The journey starts when the user chooses to sign in with a Digital Credential on the Relying Party side.

At this stage, the Relying Party redirects the browser to the DC Platform authorization endpoint. The user is not necessarily identified yet, but the DC Platform can already register that an authentication journey has been initiated by a specific Relying Party.

After the authentication request is accepted by the DC Platform, an authentication session is created and the user is presented with a QR code.

The flow is waiting for the user to scan the QR code using the DC-enabled application.

This event provides early visibility into partner usage.

It can be used to monitor:

• which Relying Party initiated the request,
• when the request was initiated,
• what scopes were requested,
• overall request volume per Relying Party.

This allows the issuer to understand how its credentials are used across relying parties.

QR code scanned — wallet application paired with the request — AuthenticationStarted

When the user scans the QR code, the DC-enabled mobile application is paired with the authentication request.

At this point, the authentication process becomes associated with the user’s iD Wallet application. This is the first stage, where the journey moves from the browser-based Relying Party context to the trusted mobile application context.

From the issuer perspective, this event is useful, because it shows that the user has actively engaged with the authentication journey.

After the request is paired with the wallet application, the user is presented with consent screen displayed in the iD Wallet mobile application.

The user can review the Relying Party request, including the identity attributes requested through the OIDC scopes.

This stage represents the point at which the user is actively engaged in the authentication journey and is able to make a decision.

Although no final outcome is produced yet, this stage is a critical precursor to all subsequent authentication events.

It can be used to monitor:

• how many displayed QR codes are actually scanned,
• conversion between browser initiation and mobile engagement,
• whether users start the journey, but do not continue on the mobile side,
• how often authentication requests reach the consent stage,
• patterns in requested scopes across relying parties,
• correlation between requested scopes and final outcomes (approval, rejection, timeout).

This helps the issuer understand not only that its credentials are being used, but also how they are being used by partner services.

Outcome of the authentication journey

Once the user is presented with the request, the authentication journey reaches its decision point.

From there, the process can follow one of several clearly distinguishable outcomes. From the issuer perspective, these outcomes define how authentication requests progress in practice and provide the basis for monitoring user behavior and system performance.

User approves request to share — AuthenticationSuccessful

If the user approves the request on consent screen in iD Wallet application, the DC Platform continues with the authentication process and prepares the authorization result. If all validations are successful, the DC Platform returns an authorization code to the Relying Party. The Relying Party can then exchange the code for an ID Token containing the approved identity attributes.

From the issuer perspective, this decision point is one of the most important monitoring stages.

It can be used to monitor:

• volume of completed authentication journeys,
• success rate across Relying Parties,
• completion rate compared to initiated requests,
• patterns in approved scopes and shared attributes,
• adoption of digital credentials across partner services.

This is typically the key event for measuring effective usage of the issuer’s credentials in the ecosystem.

User-declined request — AuthenticationDeclined

If the user explicitly rejects the request on the consent screen, the authentication process is terminated without sharing any attributes.

A high rejection rate may indicate that users do not recognize the Relying Party, do not understand the request, or are uncomfortable with the requested attributes.

This outcome can be used to monitor:

• rejection rate,
• rejection patterns per Relying Party,
• correlation between requested scopes and rejection,
• potential trust or recognition issues with specific services.

Session timeout — AuthenticationTimedOut

If no decision is made within the allowed time window, the authentication session expires.

This may occur at different stages of the journey, for example:

• before the QR code is scanned, or
• after the consent screen is displayed, but no action is taken.

This outcome can be used to monitor:

• proportion of non-completed sessions,
• drop-off before and after user engagement,
• responsiveness and engagement levels,
• potential usability or flow interruption points.

Technical failure — AuthenticationFailed

Not all authentication journeys result in a successful outcome. The DC Platform can emit unsuccessful outcome events when the process fails. In rare cases, the authentication process may fail due to an issue on the DC Platform side. This outcome indicates a backend, integration or platform-level problem rather than a user-driven decision.

Unsuccessful outcomes may include:

• occurrence of technical errors,
• stability of the authentication service,
• integration or platform issues requiring investigation,
• misconfiguration of scopes or redirect handling.

From the issuer perspective, unsuccessful outcome events are important for operational monitoring and troubleshooting.

Value for the Issuer

What the Issuer should monitor?

As an Issuer integrator, you should plan to monitor the full authentication journey, not only the final result.

Event monitoring gives the issuer visibility into the real usage of its Digital Credentials across the ecosystem.

It enables the issuer to:

• measure adoption of Digital Credential-based authentication,
• identify the most active Relying Parties,
• understand user engagement and drop-off,
• monitor consent and rejection patterns,
• detect abnormal failure rates,
• support Relying Parties during onboarding and production rollout,
• improve trust, usability, and operational reliability of the ecosystem.

In this model, the issuer does not need to store or process the personal data shared with the Relying Party in order to monitor the authentication service. The issuer receives operational visibility through events emitted by the DC Platform, while the actual identity attribute exchange remains governed by the OIDC flow, user consent, and the Digital Credential privacy model.

Online Authentication Events 

This specification provides details and schemas of authentication-related events available by the platform to the issuer.

These events cover the authentication flow and client registration lifecycle, including:

• ClientRegistered
• ClientDeleted
• AuthenticationRequested
• AuthenticationStarted
• AuthenticationSuccessful
• AuthenticationDeclined
• AuthenticationTimedOut
• AuthenticationFailed

Event Delivery model 

Events are pushed as opposed to traditional pulling. Customers are expected to expose endpoints to receive events with the following constraints:

• HTTP POST + JSON content
• Authentication supported is mTLS and/or oAuth2 The delivery model is At least once delivery which means that at events will be delivered at least once within reasonable time. Endpoints are however expected to be idempotent and tolerant reader to support forward compatibility.

Retry Logic and Retention 

After forwarding an event to the Issuer, the Event hub implements the following retry logic depending on the HTTP response from the Issuer's Backend:

• An HTTP 2xx response acknowledges reception of the event. Endpoint must ensure storage or full business processing before acknowledgement.
• An HTTP 4xx response from Issuer will either retry or abort. This is configurable.
• An HTTP 5xx response will always retry. If the Event hub fails to notify a subscriber endpoint, it will retry calling the subscriber endpoint with a default retry frequency once per second; retries continue for a retry limit of 2 hours. If the subscriber cannot be notified after 2 hours, an alarm is raised requiring manual intervention to resolve. Resolution involves correcting the issue that is preventing events from being sent to the subscriber, and then resending all events going back to the time of initial failure. This may include resending events which were properly sent if the initial failure was intermittent. As the same event may be re-sent multiple times during resolution, the subscriber endpoint’s handling of an event must be idempotent. Resolution must be completed within the retention period, which is 1 day by default, otherwise the events are permanently lost.

Note 

The retry frequency is configurable and is intended to prevent retries from overwhelming the Issuer’s subscriber endpoints. The default is 1 retry per second. The 2-hour retry limit is enforced by the Event hub and cannot be increased. The retention period is configurable and is intended to limit data retention. The default is 1 day.

Event structure 

All event are structured in the same manner

1. Common header
2. Specific payload depending on the event type

Subscription model 

The customer must define a subscriber endpoint each event they want to be notified about. IDEMIA will register each endpoint with the Event Hub on request to our SRE team.

Online Authentication Related Events 

In order to make use of the API, please log in