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.

Integration Prerequisites 

Before integrating with the Lifecycle Management APIs, ensure the following steps are completed. Each step is a hard dependency for a working integration.

1. Obtain an API key 

API keys are generated through the IDEMIA Experience Portal and are scoped to a tenant and environment. They must be included in every call to the Lifecycle Management API.

API keys are obtained after your tenant has been set up by your IDEMIA partner manager. If you do not yet have access to the Experience Portal, sign-up and ask for access. A partner manager will be in contact to help you in this process.

IMPORTANT
Treat your API key as a confidential credential. Store it securely and rotate it if it is compromised. Do not include it in source control or client-side code.

2. Expose an event endpoint 

The platform delivers lifecycle events by pushing HTTP POST requests to an endpoint you expose. You must implement and host this endpoint and request Events subscription

Your endpoint must meet the following requirements:

  • Accept HTTP POST requests with a JSON body.
  • Be reachable over HTTPS.
  • Support one of the following authentication methods: mTLS or OAuth2.
  • Return HTTP 2xx only after the event has been durably stored or fully processed. Returning 2xx before processing is complete risks data loss if your system restarts before the event is handled.
  • Be idempotent: the same event may be delivered more than once. Your endpoint must handle duplicate deliveries without producing duplicate side effects.
  • Be a tolerant reader: event payloads may contain new fields in future platform versions. Unknown fields must be ignored rather than causing failures.

3. Request Event subscriptions 

Endpoint registration is not self-service. You must contact IDEMIA's SRE team through your IDEMIA partner manager and provide the following:

  • The HTTPS URL of your subscriber endpoint (one per environment: sandbox, production ...).
  • The authentication method and credentials your endpoint will require (mTLS certificate or OAuth2 client credentials).
  • The list of event types you want to subscribe to.

Registration should be requested before integration testing begins. Contact your IDEMIA partner manager to initiate the SRE request.

4. Call the Lifecycle Management API 

Once your API key is available and your event endpoint is registered, you can call the Lifecycle Management API to initiate state updates, attribute updates, bulk operations, and ad-hoc messaging.

All requests must include:

  • The API key in the authentication header.
  • For v2 API calls (state updates, bulk updates): the x-requestId header set to a UUID (36 characters, including hyphens). This value is returned as correlationID in the resulting events, enabling end-to-end request tracing.
  • For v1 API calls (attribute updates): the optional x-correlation-id header if request tracing is required.

The API accepts requests asynchronously. A 202 Accepted response confirms the platform has queued the request — it does not confirm the final outcome. Subscribe to the relevant success and failure events to track results.

For full API details, see the Lifecycle Management API and Lifecycle Management Events references.

Glossary 

For definitions of key terms used throughout this guide — including Digital Credential, deviceCredential, credentialId, midUid, State, and related identifiers — see the Glossary.

Integration Guide sections 

Continue to the relevant page for the operations you are integrating:

  • Glossary — key terms and identifiers used throughout this guide
  • Enrollment — identity proofing, credential issuance, provisioning, and related events
  • Credential State Management — user-initiated removal, attribute updates, issuer-initiated and bulk state updates
  • MSO Renewal — MSO renewal flow, status list, and audit data storage
  • Ad-hoc Messaging — direct communication with the credential holder