Tap2iD SDK โ Windows API Reference
Complete API reference for integrating the Tap2iD Windows SDK. Initialize, verify mDLs, handle results, and evaluate security checks using BLE, NFC, or QR engagement.
Explore APIInstallation
Add the Credence ID Nexus repository to your NuGet sources in Visual Studio, then install Tap2iDSdk. Requires .NET 8.0 and Windows 11+.
NuGet Source URL
https://nexus.credenceid.com/repository/tap2id-sdk-nuget/
Auto-installed dependencies
Initialize SDK
Call InitSdk once at startup before any mDL verification. Provide your API key via CoreSdkConfig and attach result callbacks via InitSdkResultListener.
/// Initializes the SDK with the provided configuration.
public void InitSdk(
CoreSdkConfig coreSdkConfig,
InitSdkResultListener sdkInitlistener
);
CoreSdkConfig
| Property | Type | Default | Description |
|---|---|---|---|
| ApiKey | string | "" | Your Credence ID portal API key. required |
| PackageName | string | "" | Application package identifier. optional |
InitSdkResultListener delegates
Example
var config = new CoreSdkConfig { ApiKey = "YOUR_API_KEY_HERE" };
var listener = new InitSdkResultListener
{
OnInitializationSuccess = result => Console.WriteLine("SDK ready"),
OnInitializationFailure = (e, msg) => Console.WriteLine($"Failed: {e} โ {msg}")
};
sdk.InitSdk(config, listener);
Verify mDL
Call VerifyMdocAsync with the engagement string from a QR scan, NFC tap, or BLE discovery. Subscribe to DelegateVerifyState for real-time progress.
public Task<Tap2iDResult> VerifyMdocAsync(
MdocConfig mdocConfig,
DelegateVerifyState State
);
MdocConfig Properties
| Property | Type | Default | Description |
|---|---|---|---|
| DeviceEngagementString | string | "" | Encoded engagement payload. Required only when QR code engagement is requested |
| EngagementMode | DeviceEngagementMode | QrCode | Physical capture method (QrCode or Nfc). |
| BleWriteOption | BleWriteOption | Write | BLE write mode โ Write or WriteWithoutResponse. |
| IsReaderAuthentication | bool | false | Present verifier certificate to holder device. |
| NfcReaderNameFilter | string? | null | Substring to select a specific NFC reader. optional |
| NfcDeviceEngagementTimeout | int | 30s | NFC engagement wait time. Range: 5โ300. |
| BleConnectionTimeout | int | 10s | BLE scan + connect phase. Range: 5โ300. |
| BleConsentAndDataTransferTimeout | int | 30s | Consent + data transfer after connection. Range: 5โ300. |
VerifyState Lifecycle
Example
var config = new MdocConfig
{
DeviceEngagementString = qrCodeData,
EngagementMode = DeviceEngagementMode.QrCode,
BleConnectionTimeout = 15,
BleConsentAndDataTransferTimeout = 45
};
Tap2iDResult result = await sdk.VerifyMdocAsync(config, new DelegateVerifyState
{
OnVerifyState = state => Console.WriteLine($"โ {state}")
});
VerifiedDocument
| Property | Type | Description |
|---|---|---|
| DocType | string | ISO document type, e.g. org.iso.18013.5.1.mDL |
| Authentication | AuthenticationResult | Cryptographic and trust verification for this document. |
| Namespaces | List<NamespaceData> | Attributes organized by namespace โ key โ value. |
ResultError before accessing Documents โ a non-OK result may return an empty or partial list.
Retrieve Data
Iterate through Namespaces and their Items to access attribute values. Binary fields like portrait and signature_usual_mark are returned as byte[].
foreach (var doc in result.Documents)
foreach (var ns in doc.Namespaces)
foreach (var item in ns.Items)
{
if (item.Key == "portrait" && item.Value is byte[] img)
{ /* render as ImageSource */ continue; }
Console.WriteLine($"{item.Key}: {item.Value}");
}
org.iso.18013.5.1. Common fields: family_name, given_name, birth_date, document_number, portrait, driving_privileges.
Security Status
Each VerifiedDocument exposes an AuthenticationResult with five independent checks to evaluate before trusting the credential data.
var auth = doc.Authentication;
bool isTrusted = auth.TrustAttributes.IsIssuerTrusted;
bool deviceSigned = auth.SecurityChecks.IsDeviceSignedValid;
bool issuerSigned = auth.SecurityChecks.IsIssuerSignedValid;
bool digestsValid = auth.SecurityChecks.AreDigestsValid;
var msoStatus = auth.MsoValidity.Status; // Valid | NotYetValid | Expired
foreach (var err in auth.ValidationErrors)
Console.WriteLine($"Error: {err.Message}");
| Property | Type | Description |
|---|---|---|
| TrustAttributes.IsIssuerTrusted | bool | Issuing CA found in the SDK trust store. |
| SecurityChecks.IsDeviceSignedValid | bool | ECDSA/MAC device signature passes verification. |
| SecurityChecks.IsIssuerSignedValid | bool | Mobile Security Object signature is valid. |
| SecurityChecks.AreDigestsValid | bool | Data item hashes match MSO digests. |
| MsoValidity.Status | MsoStatus | Valid, NotYetValid, or Expired. |
| ValidationErrors | List<ValidationError> | Detailed issues. Empty when all checks pass. |
Class Reference
ConfigDataSource
Reads the SDK base URL from a local config file, falling back to a default when absent.
| Member | Signature | Description |
|---|---|---|
| Constructor | ConfigDataSource(string defaultBaseUrl) | Stores the fallback URL. |
| GetBaseUrl | string GetBaseUrl(string configFilePath) | Returns file URL or defaultBaseUrl if absent. |
NfcCommunicationException
Thrown when an error occurs during NFC data exchange.
| Constructor | Description |
|---|---|
NfcCommunicationException(string message) | Creates exception with descriptive message. |
NfcCommunicationException(string message, Exception inner) | Wraps the underlying NFC failure. |
CommunicationBleCentralClientMode
Manages the BLE Central role for reading from a holder device acting as a peripheral.
| Member | Type | Description |
|---|---|---|
| SetTimeout(int) | void | Overrides BLE operation timeout in seconds. |
| BleWriteOption | BleWriteOption | Acknowledged write or fire-and-forget mode. |
| ConsentStarted | EventHandler? | Fires when holder device begins consent flow. |
| ConsentEnded | EventHandler? | Fires when consent flow completes. |
| MessageReceived | MessageReceivedHandler? | Raw BLE message as byte[]. |
Error Codes
Returned via Tap2iDResult.ResultError and the OnInitializationFailure callback.
| Code | Phase | Meaning |
|---|---|---|
| OK | Any | Operation completed successfully. |
| ERROR_INIT | Initialization | SDK failed to initialize โ check API key and network. |
| ERROR_CONNECTION | Verification | BLE or NFC connection failed or timed out. |
| ERROR_TIMEOUT | Verification | A configured timeout expired before completion. |
| ERROR_VALIDATION | Verification | Security checks failed. Inspect ValidationErrors. |
| ERROR_CONSENT_DENIED | Verification | Holder declined to share credentials. |
Supported Hardware
BLE Dongles
The BLE transport uses the Bumble library and requires a compatible USB Bluetooth adapter.
| VID/PID | Device |
|---|---|
| 0BDA / A728 | Realtek BLE Adapter |
| 0BDA / 8771 | Startech Adapter / USBA-BLUETOOTH-V5-C2 |
NFC Readers
Any PC/SC compatible USB NFC reader. Most modern readers work out of the box with standard Windows drivers.
QR / Barcode
Any built-in or USB webcam, or USB barcode scanner operating as a standard HID / keyboard wedge device.