mDL Exchange API
Alpha API
The mDL Exchange API is in a private alpha state; access is restricted, and the API may drastically change with no warning.
We are actively looking for feedback and testing of this API; please contact Trinsic to learn more.
Overview
The mDL Wallet landscape is significantly fragmented, with major differences in the transport mechanisms, data formats, and security features across the major vendors. The verification process changes significantly depending both on where an mDL is stored (Apple/Google/Samsung Wallet, CA DMV, etc.) and on what client the user is verifying from (web, native app).
The mDL Exchange API simplifies all of this complexity behind two intuitive API endpoints, a lightweight client SDK, and a few string values.
Supported Wallets and Platforms
The mDL Exchange API is designed to support all mDL wallets which support a native on-device exchange mechanism, such as Digital Credentials API or similar Android / iOS native APIs.
Wallet | Verify on Web | Verify in App | Sessions API |
---|---|---|---|
Google Wallet | ✅ Supported | ✅ Supported | ℹ️ Widget and Hosted supported today. Advanced coming soon. |
Apple Wallet | 🟢 Available Soon | 🟢 Available Soon | 🟢 Available Soon |
Samsung Wallet | ⏱️ Not yet supported by wallet | ⏱️ Not yet supported by wallet | ✅ Supported |
CA DMV | ⏱️ Not yet supported by wallet | ⏱️ Not yet supported by wallet | ✅ Supported |
LA Wallet | ⏱️ Not yet supported by wallet | ⏱️ Not yet supported by wallet | ✅ Supported |
Note: "Web" here refers to a Digital Credentials API verification, whereas "Native" refers to an mDL Verification in a native Android or iOS app, using a native SDK.
The "Sessions API" column describes the support for this provider in the Sessions API, which is designed to support every digital ID provider and wallet.
How to verify credentials in unsupported mDL Wallets
A number of mDL Wallets within Trinsic's network (such as Samsung Wallet, CA DMV, LA Wallet) do not yet support a native on-device exchange API, and therefore do not fit into the mDL Exchange API paradigm.
Use the Trinsic Sessions API to verify an mDL stored in any of the wallets not supported by the mDL Exchange API.
Exchange Flow
1. Create an mDL Exchange
Call the Create mDL Exchange API endpoint, passing in the following information:
verificationProfileId
- Trinsic will provide this to you
provider
- Which wallet you are attempting to verify an mDL within
- Can be
apple-wallet
orgoogle-wallet
exchangeMechanism
- Which native API to create an mDL request for
- Can be
DigitalCredentialsApi
(to verify on web) orNativeApp
(to verify in an app)
documentType
- The document type identifier to request from the user's wallet (e.g.,
org.iso.18013.5.1.mDL
)
- The document type identifier to request from the user's wallet (e.g.,
nameSpaces
- The mdoc namespaces and fields to request from the credential
- Provider-specific configuration
- This is described in greater detail in later sections
The response to this API call contains three strings: exchangeId
, exchangeContext
, and requestObjectBase64
.
exchangeId
is a unique identifier for the exchange; save it in your backend.
exchangeContext
is an opaque, encrypted string which must be sent back to Trinsic during the Finalization step; save it in your backend.
requestObjectBase64
should be sent to your frontend (website or app) and passed into the Trinsic mDL SDK, exactly as received from the Trinsic API.
2. Invoke Client mDL SDK
Call the Trinsic mDL SDK for your environment (Web, Android, iOS), passing in the requestObjectBase64
you received in the Creation step.
If successful, the response from the Trinsic SDK will contain a token
with a string value.
Send this token
to your backend.
3. Finalize the Exchange
Once your backend has received the final token
from your web frontend or native app, call the Finalize mDL Exchange endpoint, passing in the following information:
verificationProfileId
- Same value as provided during Creation
exchangeId
- Provided to you when you created the mDL Exchange.
exchangeContext
- Pass back the
exchangeContext
which was returned to you when you created the mDL Exchange.
- Pass back the
responseToken
- The token you got from your frontend or app
As part of this API call, Trinsic will process the mDL exchange; verify all cryptographic signatures, check against trusted issuer root certificates, and verify revocation status; and process and normalize the output mDL data into an easy-to-use data model.
Client mDL SDKs
Web
CreateMdlExchange
Input
CreateMdlExchange
InputFor mDL verifications on the web, Trinsic needs to know the hostname of the page on which the Digital Credentials API will be called -- that is, the hostname in the browser bar of the page the user is interacting with.
This can be provided via the digitalCredentialsApiHost
field when creating an mDL Exchange.
For example, if the user is on the page https://verify.exampleshop.com/verify-mdl
, use the value verify.exampleshop.com
.
SDK Usage
To verify mDLs in a web browser, use the Trinsic Web UI SDK, version 2.3.0-alpha1
.
Once you have a requestObjectBase64
from your backend, invoke the Trinsic SDK like so:
import { performMdlExchange } from "@trinsic/web-ui";
const mdlResult = await performMdlExchange(requestObjectBase64); // Throws error on failure
const resultExchangeId = mdlResult.exchangeId;
const resultToken = mdlResult.token;
// Send resultToken to your backend
Android App
CreateMdlExchange
Input
CreateMdlExchange
InputFor mDL verifications in an Android app, Trinsic needs to know two pieces of information about the app which will be requesting the user's credential:
- The package name of the app (eg
com.example.app
) - The SHA-256 fingerprint of the app's signing certificate
- This should be passed to Trinsic's API in hex form (eg
01:02:03:...
), with or without colons. - For debug / local builds, this is likely contained in your local debug keystore.
- Use the command
keytool -list -keystore <path-to-debug-keystore>
to find your debug certificate's fingerprint. - The default password for Android debug keystores is
android
.
- Use the command
- This should be passed to Trinsic's API in hex form (eg
These should be passed in the androidNativeAppPackageName
and androidNativeAppSigningCertificateFingerprint
fields, respectively.
SDK Usage
To verify mDLs in an Android app, use the Trinsic Android UI SDK , version 2.1.0-alpha1
.
Once you have a requestObjectBase64
from your backend, invoke the Trinsic Android SDK:
TrinsicMdl.performMdlExchange(this, requestObjectBase64, (result) -> {
if (result.getSuccess()) {
// On success, extract token and send it to your backend
String exchangeId = result.getExchangeId();
String token = result.getToken();
sendToBackend(token);
} else {
// On fail, result contains an exception
Exception thrownException = result.getException();
}
});
iOS App
Coming Soon
Apple Wallet support is coming to this API very soon.
Updated 1 day ago