Lifecycle Management API Explorer 

This document specifies the standard REST API interface that allows an Issuer's backend to manage the lifecycle of documents (credentials).
It enables to update the state and attributes of single or multiple credentials/deviceCredentials, as well as to send direct ad-hoc messages to end-users without performing an update.

General information 

Authentication 

Two methods of authentication can be enabled:

• Authentication through OAuth2

  • IDEMIA only supports the client secret authentication method for OAuth2

• Mutual Authentication Using TLS (Transport Layer Security) also referred to as mTLS (mutual Transport Layer Security)

  • For mTLS, IDEMIA will supply the required certificates to secure the connection.

In addition to the selected authentication method, each API request must include an API key. The API key is used to identify the tenant and retrieve the corresponding tenant configuration from the backend before request processing continues.

General REST API Conventions 

All interfaces between Lifecycle Management API and Issuer's backend will use a REST API with a JSON payload.

HTTP Verbs

RESTful Lifecycle Management API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Table 1. HTTP Verbs

HTTP Status Codes

All interfaces between the Lifecycle Management API and Issuer's Backend will use a REST API with a JSON payload. REST APIs support standard HTTP/HTTPS error codes.

Table 2. HTTP Status Codes

HTTP Headers

Update Service (Lifecycle Management API) uses a correlation Id in the HTTP header of its REST interfaces to act as a reference for a specific transaction and its related event chain. Each request or message includes this correlation Id. We strongly recommend that customers implementing REST make use of this field, as it helps track transactions across different systems.

Please note that different header names and correlation ID formats are used in API versions v1 and v2.

Correlation Id

The Correlation Identifier is used to support distributed tracing of requests across services and systems. It allows operators, an Issuer's backend to track the lifecycle of a request and its related events from initiation to completion.

In the Lifecycle Management v2 API, the correlation mechanism has been standardized to improve interoperability and reliability - instead of using x-correlation-id, the request header x-requestId is now required.

Example: x-requestId: 434b05a4-510e-4589-8d5c-73d7333c3f2a

The handling of correlation identifiers has evolved between API versions:

• In the Lifecycle Management v1 API, the header x-correlation-id was used for request tracing. The requirements for this field were not strict. The value could be either:

  • a UUID, or

  • a comma-separated list of source/value pairs in the format: [value as UUID];source=[source]

  This approach offered flexibility but also led to inconsistencies in how identifiers were generated and used.

• In the Lifecycle Management v2 API, the correlation mechanism has been standardized to improve interoperability and reliability - instead of using x-correlation-id, the request header x-requestId is now required.

  The value of must be a UUID string in the canonical format (36 characters, including hyphens). If the header is omitted or provided as an empty value, an internal x-requestId will be generated.

  Clients using this header can trace the journey of a request through events (x-requestId = correlationID in event's header) and finally correlate it with the result of an update.

  This stricter definition ensures consistency across services and simplifies distributed request tracing.

Lifecycle API Design Principles

• Normalized API to separate state update from attribute update for both batch and singleton update
• Simplified batch updates for state changes
• Event driven alignment
  • Added request identifiers to support distributed tracing and event correlation.
  • Asynchronous confirmation for both singleton and batch updates.
  • All API acknowledges reception when the event is written in our event hub or batch is persisted
  • An asynchronous callback in the form of events is provided for both successful and failure cases for both singleton and batch APIs.
  • Each related events will hold the x-requestId value as correlation identifier. This means that the x-requestId from the request header sent to did-update will be used as the correlationId in events triggered by this request. The x-requestId should be provided in UUID format. If x-requestId is not sent, the correlationId will be generated according to the configuration, which is typically tcn. The Istio traceId is not a UUID.
• Aligned nomenclature with the multi Wallet model

Attribute change notification

• Added ability to convey attribute update scope of change.
  • Each attribute field will need to be identified as ADDED/UPDATED/DELETED.

Status update

• Normalized state options to align to the new Wallet model.
• Added ability to support target specific Wallet ecosystem.
• Added ability to convey state change reason code.

Terminology 

Credential

Represents a physical identity document in the DC platform

There’s a 1:1 mapping with a DL / ID card or any other issued physical document

A credential has a credentialID which is a UUID generated at first issuance within a wallet

Datagroup

Binary bundle holding a representation of a credential Usually holds:

• User Identity attributes
• Optionally: Privilege attributes
• A device authentication public key
• Issuer digital signature traceable to a trusted Issuer

Example: ISO 18013-5 datagroup

Device

Wallet client application instance holding a Digital Credential installed on the end-user physical device.

A device is identified by a deviceID. This identifier identifier the Wallet client application

DeviceCredential

Represents an instance of a credential for a given Device.

A set of datagroups will be issued for each DeviceCredentials.

ClientType

Client Type refers to the Wallet client type. This allows the issuer to be informed which Wallet a credential is being issued to.

Release version 1.2.3 

Lifecycle Management Rest API

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