Windows SDK ยท API Reference

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 API
>_ tap2id-sdk โ€“โ€“docs
01
Initialize SDK
Configure your API key and boot the SDK before performing any mDL verification sessions.
02
Verify mDL
Redefine your verification flow โ€” one async call supports QR, NFC, and BLE engagement modes.
03
Handle Results
Process multi-document transactions and inspect the structured Tap2iDResult returned by the SDK.
04
Security & Trust Checks
Adjudicate cryptographic verification, issuer trust, and MSO validity to grant higher assurance levels.
05
Class Reference
Full documentation for ConfigDataSource, BLE communications, and exception types.
06
Supported Hardware
Compatible BLE dongles, NFC readers, and barcode scanners validated for use with Tap2iD SDK on Windows.
Setup

Installation

Add the Credence ID Nexus repository to your NuGet sources in Visual Studio, then install Tap2iDSdk. Requires .NET 8.0 and Windows 11+.

โ„น Register on the Verify with Credence portal first to obtain your API license key before integrating the SDK.

NuGet Source URL

nuget.config
https://nexus.credenceid.com/repository/tap2id-sdk-nuget/

Auto-installed dependencies

BluetoothWinUI
BluetoothBumble
Tap2idBluetoothCommon
Logging
01

Initialize SDK

Call InitSdk once at startup before any mDL verification. Provide your API key via CoreSdkConfig and attach result callbacks via InitSdkResultListener.

Tap2iDSdk โ€” InitSdk()
/// Initializes the SDK with the provided configuration.
public void InitSdk(
    CoreSdkConfig        coreSdkConfig,
    InitSdkResultListener sdkInitlistener
);

CoreSdkConfig

PropertyTypeDefaultDescription
ApiKeystring""Your Credence ID portal API key. required
PackageNamestring""Application package identifier. optional

InitSdkResultListener delegates

OnInitializationSuccess(SdkInitializationResult result)
Invoked when initialization completes successfully.
OnInitializationFailure(Tap2iDResultError error, string ErrorMessage)
Invoked on failure โ€” provides structured error code and diagnostic message.

Example

C#
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);
02

Verify mDL

Call VerifyMdocAsync with the engagement string from a QR scan, NFC tap, or BLE discovery. Subscribe to DelegateVerifyState for real-time progress.

Tap2iDSdk โ€” VerifyMdocAsync()
public Task<Tap2iDResult> VerifyMdocAsync(
    MdocConfig         mdocConfig,
    DelegateVerifyState State
);

MdocConfig Properties

PropertyTypeDefaultDescription
DeviceEngagementStringstring""Encoded engagement payload. Required only when QR code engagement is requested
EngagementModeDeviceEngagementModeQrCodePhysical capture method (QrCode or Nfc).
BleWriteOptionBleWriteOptionWriteBLE write mode โ€” Write or WriteWithoutResponse.
IsReaderAuthenticationboolfalsePresent verifier certificate to holder device.
NfcReaderNameFilterstring?nullSubstring to select a specific NFC reader. optional
NfcDeviceEngagementTimeoutint30sNFC engagement wait time. Range: 5โ€“300.
BleConnectionTimeoutint10sBLE scan + connect phase. Range: 5โ€“300.
BleConsentAndDataTransferTimeoutint30sConsent + data transfer after connection. Range: 5โ€“300.

VerifyState Lifecycle

DeviceEngagementStarted
DeviceEngagementEnded
DeviceConnectionStarted
DeviceConnectionEnded
UserConsentStarted
UserConsentEnded
DataTransferStarted
DataTransferEnded
DataValidationStarted
DataValidationEnded

Example

C# โ€” QR Code Verification
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}")
});
03

VerifiedDocument

PropertyTypeDescription
DocTypestringISO document type, e.g. org.iso.18013.5.1.mDL
AuthenticationAuthenticationResultCryptographic and trust verification for this document.
NamespacesList<NamespaceData>Attributes organized by namespace โ†’ key โ†’ value.
โš  Always check ResultError before accessing Documents โ€” a non-OK result may return an empty or partial list.
04

Retrieve Data

Iterate through Namespaces and their Items to access attribute values. Binary fields like portrait and signature_usual_mark are returned as byte[].

C# โ€” Extracting Document Data
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}");
}
โœฆ Primary mDL namespace: org.iso.18013.5.1. Common fields: family_name, given_name, birth_date, document_number, portrait, driving_privileges.
05

Security Status

Each VerifiedDocument exposes an AuthenticationResult with five independent checks to evaluate before trusting the credential data.

C# โ€” Security Checks
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}");
PropertyTypeDescription
TrustAttributes.IsIssuerTrustedboolIssuing CA found in the SDK trust store.
SecurityChecks.IsDeviceSignedValidboolECDSA/MAC device signature passes verification.
SecurityChecks.IsIssuerSignedValidboolMobile Security Object signature is valid.
SecurityChecks.AreDigestsValidboolData item hashes match MSO digests.
MsoValidity.StatusMsoStatusValid, NotYetValid, or Expired.
ValidationErrorsList<ValidationError>Detailed issues. Empty when all checks pass.

Reference

Class Reference

ConfigDataSource

Reads the SDK base URL from a local config file, falling back to a default when absent.

MemberSignatureDescription
ConstructorConfigDataSource(string defaultBaseUrl)Stores the fallback URL.
GetBaseUrlstring GetBaseUrl(string configFilePath)Returns file URL or defaultBaseUrl if absent.

NfcCommunicationException

Thrown when an error occurs during NFC data exchange.

ConstructorDescription
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.

MemberTypeDescription
SetTimeout(int)voidOverrides BLE operation timeout in seconds.
BleWriteOptionBleWriteOptionAcknowledged write or fire-and-forget mode.
ConsentStartedEventHandler?Fires when holder device begins consent flow.
ConsentEndedEventHandler?Fires when consent flow completes.
MessageReceivedMessageReceivedHandler?Raw BLE message as byte[].
Reference

Error Codes

Returned via Tap2iDResult.ResultError and the OnInitializationFailure callback.

CodePhaseMeaning
OKAnyOperation completed successfully.
ERROR_INITInitializationSDK failed to initialize โ€” check API key and network.
ERROR_CONNECTIONVerificationBLE or NFC connection failed or timed out.
ERROR_TIMEOUTVerificationA configured timeout expired before completion.
ERROR_VALIDATIONVerificationSecurity checks failed. Inspect ValidationErrors.
ERROR_CONSENT_DENIEDVerificationHolder declined to share credentials.
Hardware

Supported Hardware

BLE Dongles

The BLE transport uses the Bumble library and requires a compatible USB Bluetooth adapter.

VID/PIDDevice
0BDA / A728Realtek BLE Adapter
0BDA / 8771Startech 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.

โœฆ Credence ID recommends the Mini BT540 or Mini BT542 USB adapters for best Bluetooth range and reliability.