How to Read This Guide 

This guide is structured to introduce the Digital Credential lifecycle progressively, starting with a high-level overview and then moving into individual lifecycle operations.

The first section explain the core concepts used throughout the guide, including the relationship between a credential and its device-specific instances, the identifiers used to reference them, and the events emitted by the platform. These concepts are important for understanding how lifecycle requests are scoped and how Issuer systems should process resulting events.

The next sections present a global lifecycle overview. It shows the main stages of the credential journey, beginning with credential enrollment, and continuing with the most important post-issuance processes: attribute updates, state updates and MSO renewal. This sections are intended to provide a common understanding of how the major lifecycle processes relate to one another before the guide introduces detailed integration behavior.

This guide also introduces Credential Usage Use Cases, which describe how an active Digital Credential is used after it has been issued and activated.

Unlike lifecycle management flows, usage use cases do not modify the lifecycle state of the credential. Instead, they describe interaction scenarios such as online authentication, CIBA flow, or ad-hoc messaging, and explain how these interactions may be observed or handled by Issuer systems.

The Integration Guide describes the supported Lifecycle Management flows in more detail. It covers attribute updates, issuer-initiated state updates, bulk state processing, user-initiated credential removal, MSO renewal, optional MSO Status List and audit data flows, ad-hoc messaging and online authentication.

API conventions, authentication requirements, request headers, correlation identifiers, and implementation-specific details are described separately from the business flows. They should be read as integration details that support the lifecycle operations described in this guide.

Readers who are new to the integration should start with the Global Lifecycle Overview before continuing to the detailed lifecycle sections. Readers already familiar with wallet onboarding and credential issuance may proceed directly to the Lifecycle Management sections.

Core concepts 

The following definitions introduce the main objects and identifiers used throughout Digital Credential lifecycle operations. These concepts are important for understanding how lifecycle requests are scoped, how events should be interpreted, and how Issuer systems should track credentials and their device-specific instances.

Wallet A wallet is the mobile application in which a user stores and uses Digital Credentials. In this guide, the wallet refers to the ID Wallet App. A single wallet may contain multiple Digital Credentials.

From the Issuer perspective, the wallet is where a Digital Credential is installed, becomes active, and can later be used, updated, renewed, or removed.

Digital Credential
A Digital Credential is the logical digital representation of an Issuer-issued physical document.

From the Issuer perspective, the Digital Credential is the main lifecycle object. It can be issued, updated, suspended, reinstated, revoked, or otherwise managed through lifecycle operations. A Digital Credential may exist independently of any single device and may be associated with one or more device-specific instances.

A Digital Credential is identified by a unique credentialId.

deviceCredential
A deviceCredential is the device-specific instance of a Digital Credential installed in a wallet on a particular device.

From the Issuer perspective, a deviceCredential represents the same Digital Credential on one specific device. Device-level lifecycle operations and events apply to this object, for example device-specific state changes, wallet removal, or MSO renewal.

A deviceCredential is identified by a unique midUid.

credentialId
credentialId is the unique identifier of the Digital Credential as a logical lifecycle object.

From the Issuer perspective, credentialId is used to identify and track the Digital Credential across lifecycle operations and events. It is the main reference for credential-level processing, such as attribute updates or credential-level state changes.

midUid
midUid is the unique identifier of a deviceCredential.

From the Issuer perspective, midUid is used to identify and track a specific device-bound instance of a Digital Credential. It is the main reference for device-level lifecycle operations and events, such as wallet removal, MSO renewal, or device-specific state changes.

Global Lifecycle Overview 

This guide describes how Issuer systems integrate with the Digital Credential Platform to manage Digital Credentials after issuance, track lifecycle changes, and remain synchronized with the platform state.

At a high level, the Digital Credential lifecycle consists of three main stages:

• enrollment,
• issuance,
• post-issuance lifecycle operations.

The lifecycle starts with enrollment. Depending on the tenant configuration and business decision, the user may enroll through document-based identity proofing in the ID Wallet app, or continue an issuer-initiated Direct Issuance flow based on trusted, pre-verified attributes provided by the Issuer.

After successful enrollment, the platform issues the Digital Credential. The credential is then claimed on the user’s device and becomes active in the wallet.

Once the Digital Credential is active, it becomes subject to post-issuance lifecycle operations. These operations allow the Issuer and the platform to keep the credential valid, up to date, and aligned with business or regulatory requirements.

The platform supports lifecycle operations such as:

• Digital Credential registration,
• user-initiated disenrollment, optional:
  • state updates,
  • attribute updates,
  • bulk processing,
  • Mobile Security Object (MSO) renewal,
    • MSO status list publication,
    • audit data retrieval.

From the Issuer integration perspective, lifecycle events are the primary mechanism for tracking changes and final outcomes of asynchronous operations. Issuer systems should consume these events, correlate them with the affected credential or deviceCredential, and update internal records accordingly.

Credential Enrollment 

What happens from the moment the user installs the app until the credential becomes active in the wallet?

Enrollment describes the process from the moment the user installs and opens the ID Wallet app until the Digital Credential becomes active in the wallet.

The available enrollment options depend on tenant configuration and business decisions. Each tenant can decide which enrollment flow should be used for each supported document type. For example, one document type may be handled through document-based identity proofing in the app, while another may require an issuer-initiated Direct Issuance process.

This configuration should reflect the tenant’s business requirements, regulatory constraints, and desired user journey.

For document-based identity proofing, the user starts enrollment directly in the ID Wallet app and provides the required document data as part of the process. The platform validates the enrollment request, performs the required proofing and checks, issues the Digital Credential, and enables the app to claim it on the device.

For Direct Issuance, the Issuer initiates the issuance transaction using trusted, pre-verified attributes.

Although the technical initiation happens on the Issuer side, the process should be triggered by the end-user’s request or consent. The Issuer provides the user with a QR code or deeplink, which the user uses to continue enrollment in the ID Wallet app. This option allows the Issuer to fully define the set of trusted attributes included in the user’s Digital Credential, beyond attributes extracted from a physical document.

From the Issuer perspective, enrollment is an asynchronous process. Enrollment acceptance confirms that the process has started, but it does not confirm that the credential has already been issued, claimed, or activated. Issuer systems should treat enrollment events as the source of truth for the final outcome and use them to update internal records accordingly.

Document-Based Identity Proofing Enrollment 

Identity Proofing from App is the main enrollment option in which the user starts the process directly in the ID Wallet app. The user selects the relevant document type and follows the process as part of the enrollment journey.

In this flow, the Digital Credential is created based on attributes extracted and validated from the user’s identity document. The platform validates the enrollment request, performs the required identity proofing and checks, and, if successful, issues the Digital Credential.

From the Issuer perspective, this flow is user-initiated and asynchronous. The Issuer should rely on enrollment events to track whether the Digital Credential was issued, claimed, activated, or whether enrollment failed. These events should be used to synchronize Issuer records with the platform state.

From the Issuer perspective, the enrollment outcome is not known at the moment the process starts. The Issuer should rely on enrollment events to track whether the Digital Credential was issued, claimed, activated, or whether the enrollment failed. These events should be used to synchronize Issuer records with the platform state.

IMPORTANT In this option, the Digital Credential is created based on attributes extracted and validated from the user’s physical document only.

Direct Issuance 

Direct Issuance is an issuer-initiated enrollment option based on trusted, pre-verified attributes provided by the Issuer. Unlike Document-Based Identity Proofing Enrollment, this flow is not limited to attributes extracted from an identity document. The Issuer can fully define the set of trusted attributes to be included in the user’s Digital Credential.

Although the technical initiation happens on the Issuer side, Direct Issuance should be triggered by the end-user’s request or consent.

The Issuer creates the issuance transaction and provides the user with a QR code or deeplink. The user then continues enrollment in the ID Wallet app and follows the app-guided process, during which the Digital Credential is issued, claimed on the device, and activated.

From the Issuer perspective, this flow is asynchronous. The Issuer should not treat transaction initiation or enrollment acceptance as confirmation that the Digital Credential is already active. Issuer systems should rely on enrollment events to track issuance, claim, activation, or failure, and update internal records accordingly.

IMPORTANT In Direct Issuance, the attribute set included in the Digital Credential is fully defined by the Issuer and is not limited to data derived from a physical document.

For details about Direct Issuance please check here.

Issuance process configuration 

The issuance process defines how a Digital Credential is created, populated with attributes, cryptographically signed, provisioned to the wallet, and made active on the user’s device.

After enrollment or trusted-attribute validation is completed successfully, the Digital Credential Platform prepares a new credential bundle, generates the required identifiers, and emits issuance-related lifecycle events. The ID Wallet app then claims the credential on the device, after which the Digital Credential becomes active and available for use.

From a configuration perspective, the issuance process covers the following aspects:

• the attribute model used to populate the Digital Credential;
• the ISO data representation used for the credential payload;
• the content of issuance-related events, including which attributes are exposed to the Issuer;
• the signing model used to sign the Digital Credential;
• the Digital Credential validity model, including TTL and MSO renewal behavior.

ISO Mapping 

Default ISO Mapping for Photo ID

Photo ID profile is described in annex of ISO/IEC TS 23220-4, and defines a standardized model for representing a photo identification credential in mobile document ecosystems.

By default, on issuance, the Digital Credential Platform uses an ISO-based mapping aligned with the Photo ID credential profile.

In this default configuration, credential attributes are populated using data extracted from the user’s physical document.

The default ISO mapping includes, the following attributes: Mandatory:

• family_name
• given_name
• birth_date
• portrait
• issue_date
• expiry_date
• issuing_authority
• issuing_country
• age_over_18

Optional:

• enrolment_portrait_image
• document_number
• resident_address
• resident_city
• resident_postal_code
• resident_country
• sex
• age_over_21
• age_over_25
• age_in_years

The default profile defines presence for individual attributes according to the credential profile rules (for example mandatory, optional, or recommended). The effective presence of each attribute in the issued credential may vary depending on configuration, document support, and source data availability.

Custom Attribute Configuration

Although the platform provides a default ISO Photo ID mapping, Issuer is not limited to this default configuration.

The Issuer may define a custom ISO mapping and configure which attributes should be included in the issued Digital Credential. This applies both to:

• the attributes embedded in the credential itself;
• the subset of attributes exposed in issuance-related lifecycle events.

This configuration allows the Issuer to align the Digital Credential with:

• business requirements,
• supported document types,
• regulatory constraints,
• downstream system expectations,
• privacy and data minimization policies.

For document-based identity proofing, the attribute set is typically based on data extracted from the physical identity document and validated during enrollment.

For Direct Issuance, the attribute set can be fully defined by the Issuer and is not limited to data derived from a physical identity document. This allows the credential to include trusted issuer-provided attributes beyond standard document fields.

From an integration perspective, the Issuer should ensure that the configured attribute set is consistent with:

• the intended verifier use cases,
• the event payloads expected by Issuer systems,
• future lifecycle operations such as attribute update and MSO renewal.

Issuance Events 

The platform emits issuance-related events that allow Issuer systems to track the progress and outcome of credential issuance and installation. The two primary issuance events are:

• mIDIssued
• mIDClaimed

These events serve different purposes and should be interpreted differently by the Issuer.

mIDIssued Event

The mIDIssued event indicates that a new Digital Credential bundle has been issued by the platform.

This event is emitted when the platform completes issuance of a new Digital Credential bundle. It should be treated as confirmation that the platform has successfully created or reissued the credential payload.

When mIDIssued is produced?

The mIDIssued event is produced in the following cases:

• During enrollment, after successful creation of a new identity bundle.
• During attribute update, when the Issuer requests an update of one or more attributes and the backend reissues a new identity bundle.
• During ISO Mobile Security Object (MSO) update, when new attribute hashes are issued and the MSO is signed again, resulting in a new identity bundle.

The mIDIssued event is not produced during the state update flow.

The mIDIssued event contains the identifiers required to track the issued credential and should be used to lifecycle management from Issuer side, including:

• credentialId — identifier of the Digital Credential;
• midUid — identifier of the deviceCredential.

In addition, the event may contain two distinct attribute sets:

• attributes — a map containing sensitive / PII attributes, such as:
  • firstName
  • lastName
  • picture
  • and other personal data elements
• insensitiveAttributes — a map containing non-sensitive attributes, such as:
  • loa
  • serviceLevel
  • and other non-PII operational or classification attributes

The content of both maps is configurable through the Issuance Service configuration. This means the Issuer can decide which attributes should be included in the event payload and which should remain internal to the credential only.

From the Issuer perspective, mIDIssued should be used to:

• detect that a new credential bundle has been issued or reissued;
• synchronize the latest configured attribute set exposed by the platform;
• store the identifiers required for future lifecycle operations;
• correlate the event with the original enrollment, update, or renewal flow.

At minimum, Issuer systems should store:

• credentialId
• midUid
• any configured business attributes that must be synchronized into Issuer-side records

These identifiers are required to support later lifecycle operations, including:

• attribute updates,
• state updates,
• bulk operations,
• audit and reconciliation,
• operational support.

mIDClaimed Event

The mIDClaimed event indicates that the issued Digital Credential has been claimed by the ID Wallet app on the user’s device.

This event is produced only during the enrollment flow, as confirmation that the credential has been installed on the device and activated in the wallet.

Unlike mIDIssued, the mIDClaimed event does not carry credential attributes. It contains identifiers only, including:

• the Digital Credential identifier,
• the deviceCredential identifier,
• the mobile device identifier,
• optionally, the client type.

From the Issuer perspective, mIDClaimed confirms that the credential has not only been issued by the platform, but has also been successfully claimed by the wallet, and is now active on the user’s device.

This event should therefore be treated as the confirmation of installation and activation on mobile.

In practice:

• mIDIssued confirms issuance / reissuance of the credential bundle,
• mIDClaimed confirms claiming and activation on the device.

If the Issuer needs to know whether the credential is actually active in the wallet, mIDClaimed is the key event to consume.

Issuer synchronization with issuance events

What should be synchronized and stored?

Issuer systems should use issuance events as the source of truth for credential creation, reissuance, and device activation outcomes.

At minimum, the Issuer should synchronize and store:

• credentialId — for identifying the logical Digital Credential;
• midUid — for identifying the device-specific credential instance;
• device identifier, if required for support or audit;
• the configured subset of attributes exposed in mIDIssued, if those attributes must be synchronized to Issuer systems.

This data should be retained to support:

• future lifecycle requests,
• event correlation,
• troubleshooting,
• customer support,
• audit and reconciliation,
• downstream business processing.

If multiple mIDIssued events are received over time for the same credential, Issuer systems should treat the most recent event as the latest platform-issued representation of the credential bundle, while preserving a suitable audit trail if needed.

Event processing on the Issuer side should be idempotent. The event delivery policy is at least once delivery, which means that each event is delivered at least once within a reasonable time. As a result, the same event may be delivered more than once and should be safely ignored or reprocessed without causing duplicate side effects.

Signing Configuration 

By default, the Digital Credential is signed using an IDEMIA-managed root certificate.

Depending on the deployment model and Issuer requirements, additional signing options may be supported. For example, the signing model may be adapted to align with:

• the Issuer’s trust framework,
• regulatory or legal requirements,
• Issuer-specific key ownership expectations,
• interoperability requirements for verification.

This means that, beyond the default platform-managed signing model, the solution may support alternative signing approaches according to the Issuer’s needs.

From a configuration perspective, the signing model determines:

• which party signs the Digital Credential,
• how the trust chain is established,
• and how verifiers can validate the authenticity and integrity of the credential.

DeviceCredential Validity, TTL, and MSO Renewal 

The validity period is defined inside the Mobile Security Object (MSO), which is the ISO-defined security object protecting the credential data associated with that specific deviceCredential.

By default, the TTL is set to 30 days.

The TTL is configurable. Depending on the selected configuration, a deviceCredential may either use a finite validity period with periodic MSO renewal, or remain valid without expiry. If no expiry is configured, MSO renewal is not required for that deviceCredential.

When a TTL is configured and the MSO of a given deviceCredential is approaching expiry, the mobile app automatically contacts the platform, synchronizes the current state, and renews the validity period of that deviceCredential for another 30 days.

This process happens automatically, without external user or Issuer intervention, provided that:

• the app can reach the platform,
• the deviceCredential is still eligible for renewal,
• and no lifecycle state prevents further use (like revocation).

What happens when the MSO expires and is not renewed?

If the MSO expired and the wallet cannot refresh it for a given deviceCredential, that deviceCredential remains present on the device but is considered expired. In such a case:

• the deviceCredential still exists in the wallet,
• but it may no longer be accepted by verifiers,
• and its status should be understood as expired until the MSO is successfully renewed again, if renewal is still allowed.

Integration implications

From the Issuer perspective, MSO renewal is relevant at the deviceCredential level because it refreshes the usability of the credential instance installed on a specific device.

When the MSO is renewed, the platform may reissue the credential bundle for the affected deviceCredential. This can produce a new mIDIssued event and updated deviceCredential metadata, even if the business data of the credential has not changed.

This means that Issuer systems should treat MSO renewal as part of the normal post-issuance lifecycle of a deviceCredential and be prepared to process corresponding mIDIssued event accordingly.

Post-issuance lifecycle 

What can happen after issuance?

Once a Digital Credential has been issued, claimed on the device and it enters the post-issuance phase, where it may be subject to lifecycle operations initiated by either the credential holder or the Issuer.

From the Issuer perspective, post-issuance lifecycle operations are important because they may affect the validity, usability, or state of the Digital Credential or its device-specific instances (deviceCredentials). These operations are typically processed asynchronously, and their outcome should be tracked through lifecycle events emitted by the platform.

User-initiated Digital Credential Removal 

What happens when the credential holder disenrolls a Digital Credential from the wallet?

When the credential holder removes a Digital Credential from the ID Wallet App, the corresponding deviceCredential is removed from the app and the platform updates its status.

For the Issuer, this means that the removal is reported through a lifecycle event. Issuer systems should use that event to identify the affected Digital Credential and deviceCredential, and update internal records accordingly.

IMPORTANT

• Removing a Digital Credential from the ID Wallet App triggers platform-side processing and lifecycle events.
• Deleting the ID Wallet App only removes the app from the device. It does not contact the platform and does not trigger lifecycle processing or events.

For detailed behavior, event semantics, and optional backend cleanup outcomes, refer to User-Initiated Credential Removal.

Issuer initiated lifecycle processes 

Which lifecycle operations can the Issuer initiate after the Digital Credential becomes active?

Once a Digital Credential becomes active in the wallet, the Issuer may need to keep it aligned with current business, legal, or operational requirements. For this purpose, the platform supports issuer-initiated lifecycle operations that allow the Issuer to update credential data, change credential state, or maintain credential usability over time.

From the Issuer perspective, these operations are asynchronous. Acceptance of a request only confirms that the platform has received it for processing; it does not confirm the final outcome. Issuer systems should rely on lifecycle events to determine whether the requested action was completed successfully or failed.

State Update

How can the Issuer request and track suspension, reinstatement, or revocation of a Digital Credential or deviceCredential?

State Update allows the Issuer to change the lifecycle state of a Digital Credential, one or more associated deviceCredentials, or both, depending on the request target and scope. State changes include suspension, reinstatement, and revocation.

From the Issuer perspective, state updates are important because they directly affect whether the credential, or a specific deviceCredential, remains valid and usable., but still it is an optional operation.

The request is processed asynchronously, and the final outcome is communicated through lifecycle events emitted by the platform.

State updates may be submitted either for a single credential or as a bulk request covering multiple credentials. A singleton state update targets one credential, while a bulk state update allows the Issuer to request state changes for one or more credentials within a single operation.

Issuer systems should consume the resulting lifecycle events and update internal records accordingly.

For detailed request semantics, targeting rules, and event behavior, refer to: Issuer-Initiated State Update

Attribute Update

How can the Issuer update attributes of an existing Digital Credential?

Attribute Update is an optional operation that allows the Issuer to modify selected attributes associated with an existing Digital Credential after issuance. This may be required when credential data must be refreshed, corrected, or aligned with the current source of record.

From the Issuer perspective, attribute updates are processed asynchronously. Acceptance of the request confirms that it has been received and queued for processing, but it does not confirm that the updated credential is already available on the device.

A successful attribute update will result in reissuance of the credential bundle and emission of updated lifecycle events. Issuer systems should consume these events, correlate them with the affected credential and deviceCredential, and update internal records as needed.

For detailed update behavior and event semantics, refer to: Issuer-Initiated Attribute Update

MSO Renewal 

What happens when the MSO of a deviceCredential is renewed?

MSO Renewal is a post-issuance maintenance process that helps keep a deviceCredential usable on the device over time. Each deviceCredential may have a defined validity period in its Mobile Security Object (MSO). By default, this period is set to 30 days, although it may be configured according to Issuer needs.

The TTL is configurable. In some configurations, a deviceCredential may be issued without an expiry period. In such cases, MSO renewal is not required, so MSO renewal is also optional operation.

This is a silent operation. When the MSO of a deviceCredential approaches expiry, the mobile app automatically contacts the platform, and renews the validity period without explicit action from the Issuer.

From the Issuer perspective, MSO Renewal usually does not require direct interaction. However, it may still result in renewal-related issuance events that may be consumed and correlated with the affected credential and deviceCredential.

Details you can find on: MSO renewal

Audit Data Storage

What audit data can the Issuer access?

Audit Data Storage capabilities allow the Issuer to retrieve platform records related to lifecycle processing, depending on the enabled deployment options and integration scope.

From the Issuer perspective, audit data may support troubleshooting, reconciliation, compliance reporting, operational follow-up, and investigation of lifecycle outcomes. This capability is optional and should be considered where traceability of requests, events, and resulting state changes is required.

For detailed audit capabilities and access patterns, refer to: Audit Data Storage .

MSO Status List

How can credential status be published for verifiers?

MSO Status List, also referred to as the Revocation List, is an optional mechanism for publishing the status of issued Digital Credentials based on their MSO identifiers.

The revocation mechanism has been introduced in the ISO/IEC 18013-5 amendment.

It supports near real-time revocation checking by verifiers. If a presented credential is revoked, its MSO identifier is included in the status list. If the MSO identifier is not present in the list, the credential is considered valid.

For details on availability, publication model, and verifier usage, refer to: MSO Status List.

Credential Usage Scenarios 

How can an active Digital Credential be used?

Credential Usage Scenarios describe how a Digital Credential can be used after it has been issued.

These scenarios are separate from lifecycle management flows. While enrollment, attribute update, and state update flows create, modify, or change the state of a Digital Credential, usage scenarios do not affect the credential lifecycle state. Instead, they describe interactions in which an existing active credential is used, for example during online authentication, CIBA flow, or ad-hoc messaging.

This section describes the main usage scenarios, their impact on issuer systems, and the events or actions that issuer integrators may need to handle.

• Online Authentication
• CIBA Flow
• Ad-hoc Messaging

Usage-driven events are events emitted as a result of credential usage, such as verification, access attempt, or other user-initiated interactions involving the Digital Credential.

Online Authentication 

How can a Digital Credential be used for online authentication?

Online Authentication describes how an already issued and active Digital Credential can be used as part of an authentication journey in an online channel.

In this scenario, the credential is used to support an authentication or authorization process. Depending on the integration model, this may result in authentication usage-related events that are relevant to Issuer systems.

From the Issuer perspective, this scenario is important because it shows how a credential may participate in online identity or access processes after issuance, and what information Issuer systems may need to consume or react to.

CIBA Backchannel Authentication

How is an active Digital Credential used in a CIBA-based authentication flow?

The CIBA Flow describes how an active Digital Credential may be used in a backchannel authentication journey, where authentication is initiated without a direct browser-based interaction in the same user session.

In this scenario, the Digital Credential remains active and unchanged. The credential is used as part of an authentication interaction, but no lifecycle state transition takes place. Depending on the integration model, Issuer systems may observe usage-related events.

From the Issuer perspective, this scenario is relevant because it introduces a different interaction pattern than direct online authentication, while still relying on the credential as an active authentication instrument.

Details about authentication scenarios and how to follow up: Online Authentication

Ad-hoc Messaging 

How can the Issuer send ad-hoc messages to the credential holder?

Ad-hoc Messaging describes how the platform or Issuer can communicate with the credential holder after a Digital Credential has been issued and activated.

This is not a lifecycle state-changing operation. Instead, it is a communication scenario involving an existing active credential and its wallet context. Ad-hoc messaging may be used for operational communication, service-related information, reminders, or other contextual messages relevant to the credential holder.

For more details please check: Ad-hoc messaging