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.
NOTE
An API Key should be included in the header of every request to DC API t using the following format::apiKey : <API_KEY>
2. Configure the required parameters (Optional)
The DC Platform provides ISO 23220-4 Photo ID as the default Digital Credential type, which can be used without additional customization.
If a custom document type is required, its configuration must be prepared in cooperation with an IDEMIA Partner Manager.
The preparation process includes:
-
Define the Digital Credential content
Specify the attributes and other data to be included in the Digital Credential.
-
Define the ISO mapping, if required
By default, the ISO 23220-4 Photo ID mapping is used. If the default mapping does not meet the tenant's requirements, it can be customized.
The Issuer should specify:
- The mDoc document type
- Attribute keys and data types
- Whether each attribute is mandatory or optional
- Default values, if applicable
- ISO namespaces and corresponding ISO data element identifiers
-
Define the enrollment methods
Specify which enrollment methods are available for the document type and whether selfie-based revalidation is required.
Performing your first Direct Issuance
Direct Issuance endpoints
- Transaction Creation with Enrollment Attributes
POST /direct-issuance-portal/api/v1/enrollment/qrCodeUsed to create a Direct Issuance enrollment transaction and generate the activation QR code. - ISO Mapping definition
GET /.well-known/isoMappingUsed 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 please consider:
Authentication
To integrate with Direct Issuance endpoints exposed by the DC Platform, Issuer integrators must include an API key in the request header of each request using the following format: apiKey : <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
To integrate with the DC Backend through the Direct Issuance API, issuers must provide the documentType attribute within the vnd.idemia.identity.dc namespace as part of the issuance request.
The value of documentType must correspond to one of the document types supported by the target Digital Credential definition. Specifically, it must be compatible with the values defined in the applicableDocumentTypes section of the ISO Mapping file associated with the credential.
If the provided documentType is not present in the corresponding applicableDocumentTypes list, the Direct Issuance request may be rejected by the DC Backend.
Example request:
JSON1{2 "businessProcess": "DC_DEMO-QRCODE",3 "isoMappingName": "Photo ID",4 "namespaces": {5 "org.iso.23220.1": [6 {7 "name": "lastName",8 "value": "Sample"9 },10 {11 "name": "firstName1",12 "value": "John"13 },14 {15 "name": "birthDate",16 "value": "2005-01-01"17 },18 {19 "name": "frontPortrait",20 "value": "BASE64_ENCODED_FRONT_PORTRAIT"21 },22 {23 "name": "issueDate",24 "value": "2026-01-01"25 },26 {27 "name": "expireDate",28 "value": "2030-01-13"29 },30 {31 "name": "countyCode",32 "value": "US"33 },34 {35 "name": "placeOfBirth",36 "value": "United States"37 },38 {39 "name": "nationality",40 "value": "United States"41 },42 {43 "name": "gender",44 "value": "M"45 },46 {47 "name": "is18",48 "value": "true"49 },50 {51 "name": "is21",52 "value": "false"53 },54 {55 "name": "is25",56 "value": "false"57 },58 {59 "name": "documentId",60 "value": "124cc04f-8034-4a4f-ae6a-52b0904f96dd"61 }62 ],63 "org.iso.23220.datagroups.1": [64 {65 "name": "photoIdVersion",66 "value": "1"67 }68 ],69 "vnd.idemia.identity.dc": [70 {71 "name":"credentialId",72 "value":"2bd44dd0-6a6f-4ee6-b757-6639675049c4"73 },74 {75 "name":"documentType",76 "value":"DRIVING_LICENSE"77 },78 {79 "name":"midUid",80 "value":"d6092b11-0e93-4046-ad1e-82e4679f4928"81 }82 ]83 }84 }
IMPORTANT
In the example above,documentIdmust be unique per attempt.
Two 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 ( apiKey : <API_KEY>).
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:
JSON1{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:
- In-App deeplink consumption with the DC Mobile SDK is used
- Website display after existing authentication
- SMS
IMPORTANT
This QRCode/Deeplink represents the end-user digital credential.
Special care is needed to ensure that the rightful recipient 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:
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 configured for your tenant. This mapping can be used as a reference when constructing Direct Issuance requests.
The ISO Mapping defines the namespaces and attributes available for issuing a given Digital Credential.
To retrieve the ISO Mapping, send the following request: GET /.well-known/isoMapping with the following header: apiKey:<API_KEY>
Example response:
JSON1{2 "default": {3 "name": "Photo ID",4 "applicableDocumentTypes": [5 "IDENTITY_CARD",6 "DRIVING_LICENSE",7 "RESIDENT_CARD",8 "PASSPORT",9 "ID"10 ],11 "docType": "org.iso.23220.photoid.1",12 "namespace": [13 {14 "name": "org.iso.23220.1",15 "dataElement": [16 {17 "name": "lastName",18 "isoIdentifier": "family_name",19 "mandatory": true20 },21 {22 "name": "firstName1",23 "isoIdentifier": "given_name",24 "mandatory": true25 },26 {27 "name": "birthDate",28 "isoIdentifier": "birth_date",29 "isoFormat": "date",30 "mandatory": true31 },32 {33 "name": "frontPortrait",34 "isoIdentifier": "portrait",35 "isoFormat": "binary",36 "mandatory": true37 },38 {39 "name": "issueDate",40 "isoIdentifier": "issue_date",41 "isoFormat": "date",42 "mandatory": true43 },44 {45 "name": "expireDate",46 "isoIdentifier": "expiry_date",47 "isoFormat": "date",48 "mandatory": true49 },50 {51 "name": "jurisdictionId",52 "isoIdentifier": "issuing_authority",53 "mandatory": true54 },55 {56 "name": "countyCode",57 "isoIdentifier": "issuing_country",58 "mandatory": true59 },60 {61 "name": "placeOfBirth",62 "isoIdentifier": "birthplace",63 "isoFormat": "string"64 },65 {66 "name": "nationality",67 "isoIdentifier": "nationality",68 "isoFormat": "string"69 },70 {71 "name": "gender",72 "isoIdentifier": "sex",73 "isoFormat": "integer"74 },75 {76 "name": "is18",77 "isoIdentifier": "age_over_18",78 "isoFormat": "boolean",79 "mandatory": true80 },81 {82 "name": "is21",83 "isoIdentifier": "age_over_21",84 "isoFormat": "boolean"85 },86 {87 "name": "is25",88 "isoIdentifier": "age_over_25",89 "isoFormat": "boolean"90 },91 {92 "name": "selfie",93 "isoIdentifier": "enrolment_portrait_image",94 "isoFormat": "binary"95 },96 {97 "name": "ageInYears",98 "isoIdentifier": "age_in_years",99 "isoFormat": "integer"100 },101 {102 "name": "documentId",103 "isoIdentifier": "document_number"104 },105 {106 "name": "address1",107 "isoIdentifier": "resident_address"108 },109 {110 "name": "city",111 "isoIdentifier": "resident_city"112 },113 {114 "name": "postalCode",115 "isoIdentifier": "resident_postal_code"116 },117 {118 "name": "country",119 "isoIdentifier": "resident_country"120 }121 ]122 },123 {124 "name": "org.iso.23220.datagroups.1",125 "dataElement": [126 {127 "name": "photoIdVersion",128 "isoIdentifier": "version",129 "isoFormat": "string",130 "defaultValue": "1"131 },132 {133 "name": "DG1.RawData",134 "isoIdentifier": "dg1",135 "isoFormat": "binary"136 },137 {138 "name": "DG2.RawData",139 "isoIdentifier": "dg2",140 "isoFormat": "binary"141 },142 {143 "name": "DG14.RawData",144 "isoIdentifier": "dg14",145 "isoFormat": "binary"146 },147 {148 "name": "DG15.RawData",149 "isoIdentifier": "dg15",150 "isoFormat": "binary"151 },152 {153 "name": "DG29.RawData",154 "isoIdentifier": "sod",155 "isoFormat": "binary"156 }157 ]158 },159 {160 "name": "vnd.idemia.identity.dc",161 "dataElement": [162 {163 "name": "documentType",164 "isoIdentifier": "documentType",165 "mandatory": true166 },167 {168 "name": "credentialId",169 "isoIdentifier": "credentialId"170 },171 {172 "name": "midUid",173 "isoIdentifier": "midUid"174 },175 {176 "name": "physicalDocumentExpireDate",177 "isoIdentifier": "physical_document_expiry_date"178 },179 {180 "name": "deviceCredentialExpireDate",181 "isoIdentifier": "device_credential_expiry_date"182 }183 ]184 }185 ]186 }187}
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 Verifiable Credentials may be added in the future.During issuance, the platform maps the received attributes to the corresponding target attributes according to the selected ISO mapping configuration.
IDEMIA defines a set of default attribute for the PhotoID default mapping.Within the mapping file, the
namefield 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
isoIdentifierfield defines the target attribute key produced as a result of the mapping process. This target key is placed in the corresponding ISO datagroup. 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, theisoIdentifieris used as the mapped attribute key within the data group.Example:
JSON1{2 "name": "lastName",3 "isoIdentifier": "family_name",4 "mandatory": true5 }In this example,
lastNameis the internal IDEMIA attribute key expected in the request, whilefamily_nameis 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.