Lifecycle Management Integration Guide 

Introduction 

This guide describes the lifecycle management operations available for issued digital credentials and their associated device credentials.

It explains how the platform supports post-issuance changes, including credential state updates, attribute updates, bulk processing, MSO renewal, revocation-related transparency mechanisms, and ad-hoc communication with the credential holder.

For completeness, this guide also outlines the enrollment flow to provide context for the lifecycle operations described here and to show the related events produced during issuance and activation. For the complete enrollment and issuance process, refer to the Direct Issuance Integration Guide

When do you need Lifecycle Management 

Digital Credential issued from the DC Platform have a pre-defined expiration and may not require lifecycle management.

However, lifecycle management may be required for the following:

• Attribute update
  • The privacy focused design of the DC platform means that platform never stores identity/privilege attributes centrally.
  • This means that no attribute may be updated past the issuance process unless prompted by the customer
  • Example use-cases:
    • Age attestation renewal
    • Expiration date renewal
    • Custom attribute addition/amendment
• State management
  • Depending on the use-case for the digital credential, statement management may be required to match the Customers needs.
  • An Issuer can submit a request to update:
    • the state of a single credential,
    • the state of multiple credentials in a bulk operation,
  • Example use-cases:
    • Matching the customer's end-user's database status
    • Stolen/Lost End user device
    • Fraud management

If Lifecycle Management is required, basic event connectivity may be required. See Event APIs.

Glossary 

Physical Document
A document refers to a physical credential document held by a user, such as a driver license, firearm license, or identity card. A document is identified by a document number (documentId) associated with this specific physical document at the time it was issued. It is often used during the identity proofing operation as evidence for determining Level of Assurance.

Digital Credential
A Digital Credential is tamper proof assertion of a person identity and optionally privilege that lives a person's smart device. It is cryptographically bound to the device, signed by an issuing authority and verifiable. Each Digital Credential is identified by a unique credentialId, which is assigned at the time of initial issuance and represents the logical credential at the user level.
A specific instance of a digital credential in a wallet on a device is referred to as a deviceCredential and is identified by a unique midUid that is assigned by the Digital Credential Platform.
As the Digital Credential Platform supports registering the same Digital Credential on multiple devices, a single credentialId may be associated with multiple midUid values, one for each device on which the credential is provisioned.

Datagroup
A datagroup is a binary bundle that represents a credential. It typically contains:
- user identity attributes, - optional privilege attributes, - a device authentication public key, - an Issuer digital signature traceable to a trusted Issuer. An example of such a structure is the ISO 23220-4 PhotoID mDoc.

Digital Wallet
A digital wallet is a container for digital credentials. A user can have the multiple credentials enrolled in one wallet simultaneously.
The DC platform supports the following digital wallets for digital credentials:

• IDEMIA iD Wallet
• Customer-branded iD Wallet Application
• Customer Application embedding the DC Mobile SDK

State
represents the current lifecycle status of a credential or a deviceCredential. As a general principle, the state of a credential and the states of its associated deviceCredentials are expected to be consistent. However, the platform provides flexibility that allows certain state changes to be applied to an individual deviceCredential without changing the state of the parent credential. For example, a specific deviceCredential may be suspended while the credential itself remains unchanged. Any state change applied at the credential level automatically propagates to all associated deviceCredentials, updating their states accordingly.

Credential vs. deviceCredential State Definitions.

Digital identifiers :  

This table provides a description of each digital identifier

General REST API Conventions 

All interfaces between Digital Credential backend and Issuer's Backend will use a REST API with a JSON payload.

The Update Service (did-update) is responsible for handling requests from the Issuer's Backend in Lifecycle Management. It means that all requests that change the state or attributes of a credential must be sent to this service.

HTTP Verbs 

RESTful Digital Credential backend adheres to standard HTTP and REST conventions, including the use of HTTP verbs.

HTTP Status Codes 

REST APIs support standard HTTP/HTTPS error codes.

HTTP Headers 

Digital Credential Backend uses a correlation identifier in the HTTP headers to uniquely reference each transaction and its associated event chain. Each request or message includes this identifier, which enables reliable tracking of requests across distributed systems.

Different header names and correlation ID formats are used for different APIs

Authentication 

API Key 

An API key is a technical credential used to authenticate and authorize requests sent to the platform APIs. It allows the platform to recognize the calling tenant, validate that it is permitted to access a given environment, and enforce the permissions assigned to that integration. In this sense, the API key is part of the request authentication mechanism, as it identifies the calling party at the tenant level.

Once generated, the API key must be stored securely in the tenant configuration and used by the tenant’s integration components when calling the Digital Credential Platform APIs. It should be treated as a confidential credential, protected against unauthorized access, and rotated if compromised or when operationally required. The Experience Portal also provides visibility into key validity, usage, and rotation options, which supports secure lifecycle management of the credential.

API keys are obtained through the IDEMIA Experience Portal after partner manager tenant setup.

Enrollment 

Enrollment is the process of proofing a user’s identity and provisioning a Digital Credential into a digital wallet.

A user can enroll a Digital Credential by downloading and installing the IDEMIA iD Wallet App.

The user then follows the required steps to enroll the credential in the wallet. Enrollment can start in one of two ways:

• Remote identity proofing:
  • directly in the app through document-based enrollment, where the user follows the guided steps to complete identity proofing.
• Direct Issuance QRCode
  • by scanning a QR code provided by the Issuer, where the transaction has already been created and the required attributes are already defined.

The data collected during enrollment is used to verify the user’s identity. If proofing is successful, the Digital Credential is provisioned into the user’s digital wallet.

The initial steps of the enrollment journey may differ depending on the selected enrollment option, but both paths ultimately lead to a proofing decision.

The Enrollment process can include the following processes:

• Trusted Attributes used to direct issuance
• Velocity check
• Document authentication
• Attribute matching
• Biometric matching
• Provisioning
• Notifications via Events

Remote enrollment options 

Remote enrollment leverage the ID&V Proofing processes to allow a user to remotely prove who they are pretending to be by scanning a document and performing biometric matching with liveness detection.

The Issuer can determine if whether remote enrollment is enabled and what modes are available among the following:

1. ICAO Document NFC scanning
   1. This mode offers the strongest level of assurance with the ability to read and cryptographically verify the ICAO document content, guaranteeing authenticity and content consistency.
   2. The biometric matching will be performed against the portrait extracted from the document
2. Document Authentication based
   1. This mode leverages IDEMIA's ID&V documentation for determining the document genuineness
   2. The biometric matching will be performed against the portrait extracted from the document

Customization is however not available from the experience portal. Contact your partner manager for setting up a specific mapping.

Digital Credential Direct Issuance 

The Direct Issuance enables the issuance of digital credentials based on trusted, pre-verified attribute data provided by Issuer via API. The process yields a unique QRCode that can be conveyed to the end-user by the Issuer.

Once the transaction is claimed, the user can independently complete the enrollment process on their mobile device. Completion of the process may involve biometric re-validation is requested by the Issuer.

After successful completion of the required steps, the digital identity initial validation can be finalized and the credential can be provisioned.

Detailed information about the Direct Issuance process, supported flows, and integration requirements is available in the Direct Issuance Integration Guide

Credential Issuance 

Attribute Mapping

The Digital Credential Platform provides a default attribute mapping for issuing ISO/IEC 23220-4 Photo ID mDoc credentials.

The mapping defines how source document attributes are transformed into ISO-compliant data elements included in the issued credential. It also specifies the applicable document types, the target ISO document type, namespaces, and the list of attributes to be issued.

By default, the platform issues Photo ID credentials using the following docType:

Yaml
1docType: "org.iso.23220.photoid.1"

The default mapping can be used as-is or overridden by the issuer, depending on the implementation model.

Issuers may customize the mapping by:

• defining a custom mapping file and providing it to the integrator or administrator responsible for configuration on the Digital Credential Platform side.

Mapping Configuration Structure

A mapping configuration consists of the following main sections:

Applicable Document Types

The applicableDocumentTypes section defines which input document types can use the mapping. Mentioned document type must be matched with defined in the DC Platform name of documentType.

Yaml
1applicableDocumentTypes:
2  - PASSPORT
3  - IDENTITY_CARD
4  - DRIVING_LICENSE
5  - RESIDENT_CARD

This means that the same mapping can be applied when issuing credentials based on one of the listed document types.

docType

The docType is the main identifier of the mapping file and defines the ISO credential profile that will be issued.

For the Photo ID profile, the docType is: docType: "org.iso.23220.photoid.1"

This value is defined by ISO/IEC DTS 23220-4:2025 and identifies the credential as an ISO Photo ID mDoc. This profile follows the general mDoc framework and defines a ready-to-use identity credential format for Photo ID use cases.

A mapping file contains one docType only. The Digital Credential Platform uses this value to determine which credential profile the mapping applies to during issuance.

Issuers should treat this as a fixed identifier for the Photo ID profile — Issuers should not modify the docType unless they intend to issue a different ISO-defined credential profile.

Namespaces

Credential data is grouped into namespaces. A namespace defines the logical scope of the data elements included in the credential. The default Photo ID mapping may use the following namespaces:

The default mapping primarily uses the core ISO namespace:

Yaml
1namespace:
2  - name: "org.iso.23220.1"

Data Element Mapping

Each dataElement defines how an internal platform attribute is mapped to an ISO data element.

Example:

Yaml
1namespace:
2  - name: "org.iso.23220.1"
3    dataElement:
4      - name: "lastName"
5        isoIdentifier: "family_name"
6        mandatory: true
7
8      - name: "firstName1"
9        isoIdentifier: "given_name"
10        mandatory: true
11
12      - name: "selfie"
13        isoIdentifier: "enrolment_portrait_image"
14        isoFormat: binary
15
16      - name: "countyCode"
17        isoIdentifier: "issuing_country"
18        mandatory: true
19        defaultValue: "FR"

In this example, the DC Platform attribute lastName is issued as the ISO element family_name, and firstName1 is issued as given_name.

Because both attributes are marked as mandatory: true, the platform validates whether their values are available during issuance.

The outcome of this validation depends on the issuer configuration. Missing mandatory attributes may either be reported as warnings or cause the issuance process (and whole enrollment) to fail with an error.

The selfie attribute is mapped to the ISO element enrolment_portrait_image and uses the binary format. Since the mandatory property is not defined for this element, it is treated as optional and is included only if the value is available during enrollment.

If defaultValue is defined for an attribute, it can be used when no value is provided during enrollment. For mandatory attributes, the platform validates whether a value is available either from enrollment data or from the configured default value.

Default Mapping Example

The following example shows the beginning of the default Photo ID mapping configuration.

Yaml
1applicableDocumentTypes:
2  - IDENTITY_CARD
3  - DRIVING_LICENSE
4  - RESIDENT_CARD
5  - PHOTO_ID_PASSPORT
6  - PASSPORT
7docType: "org.iso.23220.photoid.1"
8namespace:
9  - name: "org.iso.23220.1"
10    dataElement:
11      - name: "lastName"
12        isoIdentifier: "family_name"
13        mandatory: true
14      - name: "firstName1"
15        isoIdentifier: "given_name"
16        mandatory: true
17      - name: "birthDate"
18        isoIdentifier: "birth_date"
19        mandatory: true
20      - name: "frontPortrait"
21        isoIdentifier: "portrait"
22        isoFormat: binary
23        mandatory: true
24      - name: "selfie"
25        isoIdentifier: "enrolment_portrait_image"
26        isoFormat: binary
27      - name: "issueDate"
28        isoIdentifier: "issue_date"
29        isoFormat: date
30        mandatory: true
31      - name: "expireDate"
32        isoIdentifier: "expiry_date"
33        isoFormat: date
34        mandatory: true
35      - name: "jurisdictionId"
36        isoIdentifier: "issuing_authority"
37        mandatory: true
38      - name: "countyCode"
39        isoIdentifier: "issuing_country"
40        mandatory: true
41      - name: "is18"
42        isoIdentifier: "age_over_18"
43        isoFormat: boolean
44        mandatory: true
45      - name: "is21"
46        isoIdentifier: "age_over_21"
47        isoFormat: boolean
48      - name: "is25"
49        isoIdentifier: "age_over_25"
50        isoFormat: boolean
51      - name: "ageInYears"
52        isoIdentifier: "age_in_years"
53      - name: "documentId"
54        isoIdentifier: "document_number"
55      - name: "address1"
56        isoIdentifier: "resident_address"
57      - name: "city"
58        isoIdentifier: "resident_city"
59      - name: "postalCode"
60        isoIdentifier: "resident_postal_code"
61      - name: "country"
62        isoIdentifier: "resident_country"
63      - name: "gender"
64        isoIdentifier: "sex"
65  - name: "org.iso.23220.datagroups.1"
66    dataElement:
67      - name: "photoIdVersion"
68        isoIdentifier: "version"
69        isoFormat: string
70        defaultValue: "1"
71      - name: "DG1.RawData"
72        isoIdentifier: "dg1"
73        isoFormat: binary
74      - name: "DG2.RawData"
75        isoIdentifier: "dg2"
76        isoFormat: binary
77      - name: "DG14.RawData"
78        isoIdentifier: "dg14"
79        isoFormat: binary
80      - name: "DG15.RawData"
81        isoIdentifier: "dg15"
82        isoFormat: binary
83      - name: "DG29.RawData"
84        isoIdentifier: "sod"
85        isoFormat: binary

Customizing the Mapping

Issuers can override the default mapping when a different credential structure is required.

Custom mapping can be used to:

• include or exclude optional attributes,
• add recommended or conditional attributes,
• map issuer-specific source fields to ISO identifiers,
• define additional namespaces,
• add national, regional, sector-specific, or issuer-specific extensions,
• support different source document types.

A custom mapping can be configured in one of the following ways:

• Custom mapping file The issuer can define a mapping file and provide it to the integrator or Digital Credential Platform administrator for configuration.

Custom Namespace Support

In addition to ISO namespaces, issuers may define their own namespaces for data elements that are not covered by the default ISO Photo ID profile.

Custom namespaces should be used when the issuer needs to include:

• national attributes,
• regional or state-level attributes,
• sector-specific attributes,
• custom data defined by the issuer.

Example custom namespace:

Yaml
1namespace:
2  - name: "com.example.photoid.extension.1"
3    dataElement:
4      - name: "internalCustomerId"
5        isoIdentifier: "customer_id"

Issuer-defined namespaces should follow a controlled naming convention and be reviewed with the DC Platform Administrator to avoid collisions with ISO namespaces or namespaces defined by other issuers.

Summary

The default mapping defines how the Digital Credential Platform issues ISO Photo ID mDoc credentials. It specifies:

• which document types are supported,
• which ISO docType is used,
• which namespaces are included,
• which attributes are mapped,
• and whether each mapped attribute is mandatory.

Issuers can use the default mapping or deliver a custom mapping file to the integrator or Digital Credential Platform administrator.

The attribute mapping is however fully customizable as follows:

1. ISO document type
2. ISO namespace and attributes
3. Mapping depending on

Customization is however not available from the experience portal. Contact your partner manager for setting up a specific mapping.

Attributes validation

During provisioning of the credential with the ISO datagroup, failOnMissingMandatoryAttributes configuration is to provide flexibility in deciding whether the absence of mandatory attributes should only trigger a warning placed in the mIDIssued event (the default behavior) without interrupting the issuance process (soft validation), or whether the absence of any mandatory attribute should instead halt the entire identity issuance process and result in errors within mIDIssuanceFailed (hard validation).

The mID Backend supports two configurable validation modes, controlled by the failOnMissingMandatoryAttributes feature toggle:

1. Hard Validation (default, feature toggle set to true)

   The ISO Digital Credential issuance process is rejected if any mandatory field is missing. Instead of mIDIssued, an mIDIssuanceFailed event is generated. The error object in this event contains detailed information about the missing attributes and their corresponding namespaces. This mode enforces strict compliance with ISO when full attribute completeness is required. It is especially useful for document-based enrollment, where the user completes identity proofing directly in the app without external supervision and the platform must ensure that all mandatory attributes are present before issuing the credential.

2. Soft Validation (feature toggle set to false)

   The ISO Digital Credential issuance continues even if some mandatory fields are missing. Missing fields are logged and included in the warnings array within the mIDIssued event. This mode ensures smooth integration with minimal disruption while still reporting validation gaps

Credential Issuance Options

All options below are configuration available through your partner manager.

Credential expiration

The digital credential may contain an expiration date that represents the administrative validity of the credential or the underlying source document. It can be aligned with the expiration date of the physical document used during enrollment or provided by the issuer via API.

Expiration of the credential date does not automatically prevent MSO issuance or presentation; post-expiration behavior must be defined and enforced by the issuer according to the applicable lifecycle policy. The issuer is responsible for defining what should happen when the credential or source document expires.

Depending on the use case and applicable rules, an expired document may be rejected, renewed, suspended, revoked, or still used for limited identity verification purposes.

MSO Expiration

ISO MSO expiration is a mechanism that forces each devices to get a re-issued digital credential on a regular basis. This mechanism is privacy preserving to avoid the MSO from being used by colluding relying parties as a tracking mechanism but also to minimize the risk of Offline credential usage despite remote revocation being invoked.

Digital Credential have a default expiration of 30 days which is a good balance between processing overhead vs security.

This value can be typically increased if MSO status list is enabled.

MSO Status list

MSO Status list provided the ability for relying parties to have near-realtime revocation validation of MSO.

This feature is disabled by default.

MSO Auditing

Successful Issuance

If the issuance process completes successfully, the backend emits an mIDIssued event. The enrollment request is then marked as accepted.

Subscription to the mIDIssued event is optional and typically required only when the Issuer doesn't generate the credentialId.

A recommended processing flow for subscribers includes:

• storing the received event,
• responding to event hub with HTTP code 202 Accepted.

Issuance Failure

If an internal error occurs during issuance, the backend emits an mIDIssuanceFailed event.

This event indicates an internal platform error that is not expected to occur under normal conditions. If the issue persists, the Issuer should raise an exception and open a support ticket with IDEMIA.

In this case, enrollment is terminated and the user may attempt enrollment again.

Provisioning 

Credential provisioning starts after the proofing process has been successfully completed and the proofing decision has been accepted by the platform.

At this stage, the backend initiates the issuance and provisioning of the digital credential to the device.

The Digital Credential Backend performs the following actions:

For each requested device:

• A unique midUid is generated for the deviceCredential.
• A Mobile Security Object (MSO) is generated.
  • The issuanceType is set to MSO_PROVISIONING.

After successful backend issuance, the provisioning process continues on the user device.

IDEMIA iD Wallet Processing:

1. The user receives a notification confirming successful issuance.
2. The wallet emits an mIDClaimed event indicating that the credential has been successfully claimed on the device.

The backend forwards the mIDClaimed event to subscribers. Subscription to the mIDClaimed event is recommended, as it provides an acknowledgment from the device that the digital credential enrollment is completed.

A suggested processing flow for subscribers includes:

• storing the event,
• responding with HTTP 202 Accepted,
• persisting midUid and credentialId,
• setting the credential state to ACTIVE.

At this point, the enrollment and provisioning process is considered complete and successful.

Enrollment sequence diagrams 

User-Initiated Credential Removal 

The Digital Credential Platform currently supports two user-initiated actions related to credential state.

• Unenrollment of a digital credential from the iD Wallet App – this action follows the workflow described in the next section.
• Deletion of the iD Wallet App – the following action affects only the iD Wallet App and is not propagated, as it does not involve any interaction with the DC Backend. Therefore, it does not follow the workflow described in the next section.

User-Initiated Credential Removal Flow 

Attribute Updates 

Attribute Update Header 

If the Issuer wants to track a request and correlate it with related events, they can include the x-correlation-id header in the request (API v1). In that case, the provided x-correlation-id is returned in related events as correlationID.

If the x-correlation-id header is not provided, the correlationID included in events is generated according to the platform configuration, typically based on the TCN. Such a trace identifier is not a UUID.

For details please check OpenAPI of Lifecycle Management and Lifecycle Events

Attribute Updates Overview 

Attribute updates are initiated by Issuers for the following purposes:

• Processing changes to demographic data
• Updating age-related fields annually on the enrolled user's birth date

Attribute updates are processed for a digital credential (credentialId) and apply to all digital credential instances (deviceCredentials) enrolled in digital wallets.

The attribute update process consists of two steps:

1. Attribute update scheduling — processed for all deviceCredentials, regardless of their state.
2. Attribute update provisioning — processed only for ACTIVE deviceCredentials.

For SUSPENDED credentials, deviceCredentials pending attribute updates are processed once the digital credential is REINSTATED.

During these steps, notifications may be sent to the Issuer through Events.

IMPORTANT
Attribute updates are allowed only for ACTIVE or REINSTATED credentials. Requests for SUSPENDED credentials are rejected.

Attribute Updates Workflow 

Attribute Update Scheduling

Attribute Update Provisioning

Issuer-Initiated Credential State Updates 

State update header 

For the Lifecycle Management endpoints IDEMIA expects the caller to include an x-requestId in the HTTP header of all v2 Lifecycle Management APIs. The x-requestId serves as a reference for a particular transaction. It is in UUID format and consists of exactly 36 characters (including hyphens).

If the x-requestId header is missing or empty, an internal x-requestId is automatically generated. In that case, the provided x-requestId is returned in related events as correlationID in event's header.

Example : x-requestId: '1c32ea85-06ee-4453-9c02-eb18bf6bb9719'

The same x-requestId is propagated to emitted events, enabling full traceability between requests, events, and processing outcomes.

Issuer-Initiated Credential State Update Overview 

Issuers can initiate state updates either for an entire credential or for a specific deviceCredential.

In lifecycle management requests, the state field represents the intended target state requested by the Issuer. The scope and behavior of the update depend on the combination of:

• targetRecordTypes,
• the recordIdentifierType provided (documentId, credentialId, or midUid).

Target Record Types Behavior 

TargetRecordTypes is an optional parameter provides the ability to alter state for credential and deviceCredential independently.

The default value is targeting both - credential and deviceCredential.

targetRecordTypes: ["CREDENTIAL"]

Only the credential state stored in the DC Backend is updated. No state updates are propagated to deviceCredentials in end-user mobile apps.

IMPORTANT
Exception: Credential revocation additionally triggers cleanup of all associated deviceCredentials (see details below).

Record Identification :  

State Effect :  

targetRecordTypes: ["DEVICE_CREDENTIAL"]

Only deviceCredential records are updated. The credential state is not affected.

midUid limits the update to a single deviceCredential.

IMPORTANT
Exception: The last deviceCredential revocation additionally triggers cleanup of associated credential.

Record Identification :  

State Effect :  

targetRecordTypes: ["CREDENTIAL", "DEVICE_CREDENTIAL"]

Both Credential and DeviceCredential records may be updated.

Processing order:

1. Credential state update
2. DeviceCredential state update

Behavior modifiers:

• If recordIdentifierType = midUid:
  • Credential is updated
  • Only the specified deviceCredential is updated

Confirmation events emitted after a successful state change include both previousState and newState. The newState reflects the effective state after the change has been applied in accordance with the Issuer’s request.

Success Events :  

Failure Events :  

Failure events include error details describing the reason for the failure.

Supported state updates include:

• Suspending a credential or deviceCredential so that it cannot be used (Issuer sends requested state as SUSPENDED)
• Reinstating a suspended credential or deviceCredential so that it becomes usable again (Issuer sends requested state as REINSTATED)
• Unlinking, revoking, or deleting a digital credential or deviceCredential (Issuer sends requested state as REVOKED)

Credential Deletion

A credential in the REVOKED state is removed from the system. As a result, no credential state is stored in the DC Backend.

Likewise, if a deviceCredential is UNLINKED, it is removed from the DC Backend.

If removed digitalCredential was the last deviceCredential assigned to credential then credential data are removed from backend and new event mIDCredentialRemoved is produced

Bulk State Update 

Bulk State Update allows the Issuer to submit a single request containing state update instructions for multiple Digital Credentials.

Unlike a singleton state update, which processes a single record per request, a bulk request contains an array of individual update entries. Each entry is processed independently using the same rules and validation logic as a standard singleton state update - it means that as a result, a single bulk request may produce a mix of successful and failed update results across its entries.

Bulk processing is asynchronous. Submitted requests are not processed immediately. Instead, they are picked up by a scheduler configured at the tenant level and executed according to the tenant-specific schedule.

As the batch is processed, the platform emits the corresponding events for each individual Credential or deviceCredential, depending on the request scope and processing outcome.

A bulk request is composed of multiple single update instructions contained in the updates array.

For details please check Lifecycle Management OpenAPI and Lifecycle Events.

Issuer-Initiated State Updates Flow 

Mobile Security Object (MSO) Renewal 

Digital Credentials issued to a iD Wallet include ISO data groups with a Mobile Security Object (MSO) to ensure freshness. The MSO includes a Time-To-Live (TTL), which defaults to 30 days. After that period, the MSO is no longer valid.

Digital wallets detect MSO expiration automatically.

No action from the Issuer or user is required to initiate MSO renewal.

MSO renewal provisioning is triggered when the iD Wallet detects that the current Mobile Security Object (MSO) is expired or close to expiration. The expiration check is triggered when the app starts and whenever the credential is presented for verification.

If the MSO has expired, the iD Wallet apps call the IDEMIA DC platform and request an asynchronous MSO renewal. This process checks salt configuration, validate sent Merkle Tree, refreshes the MSO and issues the updated MSO.

MSO renewal provisioning may emit the following events:

• mIDIssued
• mIDIssuanceFailed

These events allow the Issuer to track the result of the renewal process and correlate it with the wallet request.

The current Digital Credential app workflow is shown below.

MSO Renewal Provisioning Flow 

MSO Status List 

The MSO Status List is an optional, backward-compatible feature based on an amendment to ISO 18013-5. It adds support for storing MSO status lists, enabling near real-time MSO revocation checks — a capability not included in the original specification.

When enabled, this feature supports both:

• verifier-side MSO validity checks, and
• Issuer-side compliance and audit requirements.

Whenever a credential is registered, reissued (for example, after attribute updates) or its MSO is renewed, new attribute hashes are generated and the Mobile Security Object (MSO) is overwritten.

When the MSO Status List feature is enabled, the platform enhances the standard MSO provisioning flow with additional MSO status metadata. In particular:

• a unique msoUid is generated,
• a bucketId is generated for the corresponding status list,
• a StatusListInfo element is embedded in the MSO.

This additional MSO element contains:

• an MSO identifier,
• a status list URI pointing to the published MSO Status List.

The status list URI has the following logical form:

Text
1https://mso-status.<tenant-domain>/status/<bucketId>

This URI allows verifiers to check whether the MSO presented during verification has been revoked.

Verifier-Side Behavior with Status List

During offline verification, the verifier can extract the MSO Status List URI from the presented MSO and use it to validate the MSO status. The verification outcome is interpreted as follows:

• If the MSO is not present in the list, it is considered valid.
• If the MSO appears in the list, it is revoked and cannot be positively verified.

The MSO Status List contains only revoked MSOs. This mechanism enables efficient and standards-aligned revocation checking without requiring direct interaction with the Issuer during the verification step.

Status List from Issuer perspective

When MSO provisioning completes successfully and the MSO Status List feature is enabled, the platform generates and stores a MobileSecurityObjectsInfo object.

This object contains:

• MSO expiration information,
• MSO identifiers,
• MSO public keys,
• the statusListBucketId,
• the statusListUri.

JSON
1{
2  "mobileSecurityObjectsExpiration": "<ISO 8601 UTC timestamp>",
3  "mobileSecurityObjects": {
4    "<msoUid>": {
5      "issuerAuth": "<Base64 encoded cbor>",
6      "publicKey": "<Base64 encoded mso public key>",
7      "statusListBucketId": "<bucketId>",
8      "statusListUri": "https://mso-status.<tenant-domain>/status/<bucketId>"
9    }
10  }
11}

To expose this information to the Issuer, the platform emits a dedicated event MobileSecurityObjectsIssued after successful MSO provisioning when the MSO Status List feature is enabled.

Its purpose is to provide the Issuer with access to MSO metadata, including the URL of the published MSO Status List.

JSON
1"payload": {
2    "credentialId": "a7a82462-3f72-4f42-ba8a-73fb6c7269dd",
3    "midUid": "c6c74456-dbe3-4d9b-b68d-0c13a48f048a",
4    "clientType": "IDEMIA",
5    "mobileSecurityObjectsInfoUrl": "https://test-platform.com/msoinfo/ffe9f213-1999-421f-9d92-b9cacceaec7d/94429287-ee58-472b-bc63-7fff898773d0/a5635406-acae-42bf-9a36-66b1fe098d31?X-Security-Token=IQoJb...",
6    "mobileSecurityObjectsInfoUrlExpiration": "2027-01-14T10:55:31.820Z"
7  }

This event contains a pre-signed URL that allows the Issuer to retrieve the corresponding MobileSecurityObjectsInfo.

NOTE
Pre-signed URLs are time-limited and remain valid for 2 hours. The Issuer should retrieve the referenced object within that period.

Recommended Issuer Processing

If subscribed to this event, the Issuer should:

• Receive and store the MobileSecurityObjectsIssued event.
• Acknowledge receipt with HTTP 202 Accepted.
• Retrieve the pre-signed URL from the event payload.
• Download the MobileSecurityObjectsInfo object.
• Store the downloaded metadata for operational reference or compliance purposes.
• Extract and retain the statusListUri for the relevant MSO.

Subscription to MobileSecurityObjectsIssued event is optional, but recommended when the Issuer needs visibility into MSO-level status list metadata.

This mechanism provides an efficient, standards-aligned revocation check.

Relationship to Standard Issuance Events

The MSO Status List flow extends the standard MSO provisioning process. In addition to MobileSecurityObjectsIssued after successful MSO re-creation, the platform also emits the standard issuance events:

• mIDIssued — confirms successful MSO provisioning,
• mIDIssuanceFailed — indicates a provisioning failure caused by an internal platform error.

If subscribed, the Issuer should store these events and acknowledge them with HTTP 202 Accepted.

MSO Status List —​ Changes in MSO Issuance Flow

Audit Data Storage 

Issuer systems may need to keep records required for audit, compliance, dispute resolution, or operational investigation.

To support this requirement, the Digital Credential Platform can expose ISO Audit Data generated during MSO provisioning. This includes the ISO/IEC 18013-5 content produced for a given deviceCredential and allows the Issuer to retrieve, decrypt, and store the data required for compliance and audit purposes.

The available audit data includes:

• full Digital Credential attribute set,
• Mobile Security Object(s) (MSOs),
• salt(s),
• device public key,
• MSO Status List metadata.

IMPORTANT
Generation of audit data requires the MSO Status List feature to be enabled.

NOTE
Long-term storage of ISO Audit Data may also be provided by IDEMIA on behalf of the Issuer, subject to configuration and commercial agreement.

This functionality extends the standard MSO provisioning flow and is available when the required feature toggle is enabled.

Access to audit data is provided through event MobileSecurityObjectsIssued, allowing the Issuer to retrieve MobileSecurityObjectsInfo and hence download and store the data.

JSON
1"payload": {
2    "credentialId": "a7a82462-3f72-4f42-ba8a-73fb6c7269dd",
3    "midUid": "c6c74456-dbe3-4d9b-b68d-0c13a48f048a",
4    "clientType": "IDEMIA",
5    "mobileSecurityObjectsInfoUrl": "https://test-platform.com/msoinfo/ffe9f213-1999-421f-9d92-b9cacceaec7d/94429287-ee58-472b-bc63-7fff898773d0/a5635406-acae-42bf-9a36-66b1fe098d31?X-Security-Token=IQoJb...",
6    "mobileSecurityObjectsInfoUrlExpiration": "2027-01-14T10:55:31.820Z"
7  }

IMPORTANT
This flow uses the same MobileSecurityObjectsIssued event as the MSO Status List flow. The difference is that the corresponding MobileSecurityObjectsInfo object additionally includes the encryptedAuditData section.

If feature toggle enabled, for each successful mIDIssued event with issuanceType = MSO_PROVISIONING, the platform additionally emits a dedicated event: MobileSecurityObjectsIssued

This event provides the Issuer with a pre-signed URL to retrieve a MobileSecurityObjectsInfo object.

The MobileSecurityObjectsInfo contains:

• MSO expiration information,
• MSO metadata,
• status list references,
• access information for encrypted ISO Audit Data.

A logical representation of the structure is shown below:

JSON
1{
2  "mobileSecurityObjectsExpiration": "<ISO 8601 UTC timestamp>",
3  "mobileSecurityObjects": {
4    "<msoUid>": {
5      "issuerAuth": "<Base64 encoded cbor>",
6      "publicKey": "<Base64 encoded mso public key>",
7      "statusListBucketId": "<bucketId>",
8      "statusListUri": "https://mso-status.<tenant-domain>/status/<bucketId>"
9    }
10  },
11  "encryptedAuditData": {
12    "prefix": "<storage prefix>",
13    "preSignedUrl": "<presigned URL>",
14    "preSignedUrlExpiration": "<ISO 8601 UTC timestamp>"
15  }
16}

Audit data is encrypted using JWE (JSON Web Encryption). Only the Issuer can decrypt it using a private key associated with a certificate based on ECC P-256 keys.

This ensures that:

• audit data remains confidential in transit and at rest,
• only the Issuer can access the plaintext content,
• the platform can securely expose compliance data without disclosing it to third parties.

Recommended Issuer Processing 

If the Issuer subscribes to MobileSecurityObjectsIssued for MSO status list and audit data, the recommended processing flow is as follows:

• Receive the MobileSecurityObjectsIssued event from the Event Hub.
• Store the event for traceability and audit purposes.
• Respond with HTTP 202 Accepted.
• Extract the pre-signed URL to MobileSecurityObjectsInfo from the event payload.
• Download the MobileSecurityObjectsInfo object.
• Store MobileSecurityObjectsInfo.
• Extract the pre-signed URL to encryptedAuditData.
• Download the encrypted audit payload.
• Store the encrypted payload.
• Decrypt the ISO Audit Data using the Issuer’s private key.
• Store the decrypted audit data in the Issuer’s repository.

IMPORTANT
All pre-signed URLs are time-limited and remain valid for 2 hours. The Issuer is responsible for retrieving the referenced objects within that validity window.

The audit data storage flow, showing differences from the standard MSO renewal provisioning process, is illustrated below.

Audit Data Storage - Changes in MSO Issuance Flow 

Ad-hoc Messaging 

Ad-hoc messaging allows the Issuer to send a plain text message to the end user without requesting any change to the credential state and without updating any credential attributes. End-user receives push notification, the mobile app fetches ad-hoc message it is then displayed to the app user.

These messages are delivered to the enrolled credential holder of the iD Wallet application and are intended for informational purposes only.

The platform also supports delivery without a visible push notification by using a silent push mechanism. In this case, the application is notified in the background and can retrieve the ad-hoc message without displaying a standard push notification to the user.

NOTE
No events are emitted as part of this flow. Therefore, no x-correlation-id is expected in the request header.

Ad Hoc Messaging Workflow