Digital Credential Direct Issuance Integration Guide 

When to use Direct Issuance 

Direct Issuance may be used for the following typical use-cases:

  • Issuer already had a user-base with trusted identity attributes
  • Issuer uses a custom identity proofing/enrollment process
  • Issuer requires a custom digital credential profile (document type and attribute set)

How to integrate? 

Direct Issuance endpoints are exposed by the DC Platform and are intended for backend-to-backend integration between the Issuer system and the DC Backend.

To integrate with Direct Issuance, the Issuer should complete both tenant configuration activities and technical integration steps.

Integration Prerequisites 

Before using Direct Issuance APIs, the Issuer should work with the IDEMIA partner manager to define the required tenant setup.

As part of this preparation, the Issuer should:

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 Direct Issuance 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. Configure the required parameters (Optional)

The DC platform provides support of ISO 23220-4 PhotoID as default credential which can be used as is.

However, if a custom document type is needed, preparation with an IDEMIA partner manager is required.

As part of this preparation:

  1. Define the digital credential content that is needed. 2. By default ISO 23220-4 PhotoID will be used 3. OPTIONAL: Define the ISO mapping according to your tenant’s needs by customizing the ISO mapping.
    The Issuer should specify:

    • mDoc ISO type
    • Attribute key and data type
    • required attributes specification (mandatory vs optional)
    • default values, if applicable,
    • ISO namespaces and ISO attribute names

  2. Define which enrollment methods (with or without selfie revalidation)

Performing your first Direct Issuance 

Direct Issuance endpoints

  1. Transaction Creation with Enrollment Attributes
    POST /direct-issuance-portal/api/v1/enrollment/qrCode Used to create a Direct Issuance enrollment transaction and generate the activation QR code.
  2. ISO Mapping definition
    GET /.well-known/isoMapping Used to retrieve the ISO mapping available for the tenant (optional)

After the tenant configuration has been made available on the DC Platform, perform a control test of the Direct Issuance flow.

As part of this test:

Authentication

To integrate with Direct Issuance endpoints exposed by the DC Platform, Issuer integrators must use an API key.

Access to the DC Backend requires an API key generated through the IDEMIA Experience Portal. API keys are scoped to a specific tenant and environment and become available once the tenant has been set up by the IDEMIA partner manager.

The API key must be included in the request header for each Direct Issuance API call, as mentioned in Integration Prerequisites.

The Issuer system is responsible for securely storing and using the API key. The key should not be exposed to the mobile application, browser client, end user, or any untrusted environment.

Prepare the Direct Issuance request

Language not specified
1Example request:
2```JSON
3{
4"businessProcess": "DC_DEMO-QRCODE",
5"isoMappingName": "Photo ID",
6"namespaces": {
7    "org.iso.23220.1": [
8    {
9        "name": "lastName",
10        "value": "Sample"
11    },
12    {
13        "name": "firstName1",
14        "value": "John"
15    },
16    {
17        "name": "birthDate",
18        "value": "2005-01-01"
19    },
20    {
21        "name": "frontPortrait",
22        "value": "BASE64_ENCODED_FRONT_PORTRAIT"
23    },
24    {
25        "name": "issueDate",
26        "value": "2026-01-01"
27    },
28    {
29        "name": "expireDate",
30        "value": "2030-01-01"
31    },
32    {
33        "name": "countyCode",
34        "value": "US"
35    },
36    {
37        "name": "placeOfBirth",
38        "value": "United States"
39    },
40    {
41        "name": "nationality",
42        "value": "United States"
43    },
44    {
45        "name": "gender",
46        "value": "M"
47    },
48    {
49        "name": "is18",
50        "value": "true"
51    },
52    {
53        "name": "is21",
54        "value": "false"
55    },
56    {
57        "name": "is25",
58        "value": "false"
59    },
60    {
61        "name": "documentId",
62        "value": "124cc04f-8034-4a4f-ae6a-52b0904f96dd"
63    }
64    ],
65    "org.iso.23220.datagroups.1": [
66    {
67        "name": "photoIdVersion",
68        "value": "1"
69    }
70    ]
71  }
72}
73

74```

IMPORTANT
In the example above, documentId must be unique per attempt.

2 default business process are ready to use:

  • DC_DEMO-QRCODE: Main business process for Direct Issuance.
    • This Business process will require Selfie validation when claiming the Digital Credential
  • DC_DEMO-QRCODE-NO-SELFIE: Business process for Direct Issuance without Selfie validation
    • No authentication will be required by the end-user when claiming the Digital Credential

Attribute values are provided by the Issuer’s operator or by the Issuer backoffice system, the API key is included in the request header.

By default, an ISO 23220-4 Photo ID mDoc credentials will be issued.

Submit the request

To create an Digital Credential enrollment token Simply post to POST /direct-issuance-portal/api/v1/enrollment/qrCode
A QRCode/Enrollment Deeplink is provided as a response
Example response:

JSON
1{
2  "transactionId": "f194af6b-b87e-44f1-b1d8-f7b420386dbe",
3  "status": "EXPECTING_INPUT",
4  "base64QrCode": "<QRCode>",
5  "enrollmentUrl": "<Enrollment Deeplink>"
6}
  • transactionId — unique identifier of the enrollment process,
  • base64QrCode — generated activation QR code,
  • status — current status of the enrollment process,
  • enrollmentUrl — QR code destination URL.

The QRCode/deeplink represents a unique transaction. This transaction as a default lifespan of 30 minutes before is removed from the system.

Conveying the QRCode to the end-user is the responsibility of the Issuer. Typical use-case for conveying the QRCode:

  1. In-App deeplink consumption with the DC Mobile SDK is used
  2. Website display after existing authentication
  3. Email
  4. SMS

IMPORTANT
This QRCode/Deeplink represents the end-user digital credential.
Special care is needed to ensure that the rightful recepient claims the Digital Credential. User authentication constraints highly depend on method for conveying the QRCode/Deeplink.

Enforcing Selfie validation is highly recommended.

Note
When using the default ISO Mapping (PhotoID), the credential is usable as is online through the OIDC endpoint or in-person through our iD Verify application. When a custom document type is needed, configuration might be needed for support the custom set of attributes. Check with your IDEMIA partner manager.

Claiming the Digital Credential

After consuming the activation QR code or deeplink, the end user opens the iD Wallet app and continues the enrollment process.

Scan the generated QR code or open the deeplink using the downloaded iD Wallet application. The test user can download the iD Wallet application from the official application store:

Download for iPhone
Download for Android

The QR code contains the information required to connect the mobile app with the created Direct Issuance transaction. After the QR code is scanned, the app submits the required OTP automatically and the DC Backend validates it.

Once the transaction is connected with the mobile app, the remaining enrollment steps depend on the configured business process. For Direct Issuance, the credential may be issued immediately after claiming the transaction, or the user may be required to complete additional verification, such as selfie capture and face matching against the portrait provided by the Issuer.

After successful issuance, the Digital Credential is claimed by the mobile app and becomes active on the user’s device.

The app registers the online authentication key and the platform emits the mIDClaimed event. This event indicates that the credential has been successfully claimed on the device.

From the Issuer perspective, the enrollment should be considered complete only after the relevant success event has been received and processed. At this point, the Issuer system should store the midUid, credentialId, and the active state of the credential.

IMPORTANT
In Direct Issuance, the Digital Credential attribute set is fully defined by the Issuer through trusted, pre-verified data provided via API. It is not limited to attributes extracted from a physical document during mobile enrollment. Transaction creation, QR code generation, or enrollment acceptance should not be treated as final confirmation that the Digital Credential is active. The Issuer system should use platform events as the source of truth for tracking issuance, claim, activation, and failure outcomes.

Retrieving the ISO Mapping 

Retrieve the ISO Mapping available for your tenant may be usefull to understand how to structure the direct issuance request.

The ISO mapping defines the namespaces and attributes that can be used to issue a given Digital Credential.

GET /.well-known/isoMapping

withe example response:

JSON
1{
2  "default" : {
3    "name" : "Photo ID",
4    "applicableDocumentTypes" : [ "IDENTITY_CARD", "DRIVING_LICENSE", "RESIDENT_CARD", "PASSPORT" ],
5    "docType" : "org.iso.23220.photoid.1",
6    "namespace" : [ {
7      "name" : "org.iso.23220.1",
8      "dataElement" : [ {
9        "name" : "lastName",
10        "isoIdentifier" : "family_name",
11        "mandatory" : true
12      }, {
13        "name" : "firstName1",
14        "isoIdentifier" : "given_name",
15        "mandatory" : true
16      }, {
17        "name" : "birthDate",
18        "isoIdentifier" : "birth_date",
19        "isoFormat" : "date",
20        "mandatory" : true
21      }, {
22        "name" : "frontPortrait",
23        "isoIdentifier" : "portrait",
24        "isoFormat" : "binary",
25        "mandatory" : true
26      }, {
27        "name" : "issueDate",
28        "isoIdentifier" : "issue_date",
29        "isoFormat" : "date",
30        "mandatory" : true
31      }, {
32        "name" : "expireDate",
33        "isoIdentifier" : "expiry_date",
34        "isoFormat" : "date",
35        "mandatory" : true
36      }, {
37        "name" : "jurisdictionId",
38        "isoIdentifier" : "issuing_authority",
39        "mandatory" : true
40      }, {
41        "name" : "countyCode",
42        "isoIdentifier" : "issuing_country",
43        "mandatory" : true
44      }, {
45        "name" : "placeOfBirth",
46        "isoIdentifier" : "birth_place",
47        "isoFormat" : "string"
48      }, {
49        "name" : "nationality",
50        "isoIdentifier" : "nationality",
51        "isoFormat" : "string"
52      }, {
53        "name" : "gender",
54        "isoIdentifier" : "sex"
55      }, {
56        "name" : "is18",
57        "isoIdentifier" : "age_over_18",
58        "isoFormat" : "boolean",
59        "mandatory" : true
60      }, {
61        "name" : "is21",
62        "isoIdentifier" : "age_over_21",
63        "isoFormat" : "boolean"
64      }, {
65        "name" : "is25",
66        "isoIdentifier" : "age_over_25",
67        "isoFormat" : "boolean"
68      }, {
69        "name" : "selfie",
70        "isoIdentifier" : "enrolment_portrait_image",
71        "isoFormat" : "binary"
72      }, {
73        "name" : "ageInYears",
74        "isoIdentifier" : "age_in_years"
75      }, {
76        "name" : "documentId",
77        "isoIdentifier" : "document_number"
78      }, {
79        "name" : "address1",
80        "isoIdentifier" : "resident_address"
81      }, {
82        "name" : "city",
83        "isoIdentifier" : "resident_city"
84      }, {
85        "name" : "postalCode",
86        "isoIdentifier" : "resident_postal_code"
87      }, {
88        "name" : "country",
89        "isoIdentifier" : "resident_country"
90      } ]
91    }, {
92      "name" : "org.iso.23220.datagroups.1",
93      "dataElement" : [ {
94        "name" : "photoIdVersion",
95        "isoIdentifier" : "version",
96        "isoFormat" : "string",
97        "defaultValue" : "1"
98      }, {
99        "name" : "DG1.RawData",
100        "isoIdentifier" : "dg1",
101        "isoFormat" : "binary"
102      }, {
103        "name" : "DG2.RawData",
104        "isoIdentifier" : "dg2",
105        "isoFormat" : "binary"
106      }, {
107        "name" : "DG14.RawData",
108        "isoIdentifier" : "dg14",
109        "isoFormat" : "binary"
110      }, {
111        "name" : "DG15.RawData",
112        "isoIdentifier" : "dg15",
113        "isoFormat" : "binary"
114      }, {
115        "name" : "DG29.RawData",
116        "isoIdentifier" : "sod",
117        "isoFormat" : "binary"
118      } ]
119    } ]
120  }
121}

NOTE

The Direct Issuance request expects the attribute key and value. The DC Platform will store the attribute within the IDEMIA MerkleTree-based datagroup that serves as source of truth for derivation to other formats, ISO 18013-5 mDOC for now but other format like SD-JWT, W3C VC maybe added in the future. During processing, the platform translates the attributes into the appropriate ISO-compliant attributes based the iso mapping specifications.



IDEMIA defines a set of default attribute for the PhotoID default mapping.

Within the mapping file, the name field of a data element refers to the attribute key defined in IDEMIA’s internal attribute format. This key is used by the DC Platform to identify the source attribute received in the Direct Issuance request.

The isoIdentifier field defines the target attribute key produced as a result of the mapping process. This target key is placed in the corresponding ISO data group. It may be an ISO-compliant attribute, if the attribute is defined by the applicable ISO specification, or a custom attribute, if no standard ISO equivalent exists. In both cases, the isoIdentifier is used as the mapped attribute key within the data group.

Example:

JSON
1{
2      "name": "lastName",
3      "isoIdentifier": "family_name",
4      "mandatory": true
5    }

In this example, lastName is the internal IDEMIA attribute key expected in the request, while family_name is the mapped attribute key used in the ISO data group. Details about attribute mapping file construction you can find in Enrollment chapter — Credential Issuance subchapter.

Direct Issuance sequence diagrams 

Enrollment: Digital Credential Direct Issuance with Selfie Validation
Digital Credential Direct Issuance with Selfie Validation
Enrollment: Proofing decision and provisioning
Enrollment with Proofing Rejected or Accepted and Provisioning Flow