Overview

The cordova-ts-authentication plugin brings Mosaic Authentication to a Cordova app on iOS and Android. It exposes passkeys (WebAuthn), native biometrics, PIN code, TOTP, and device-key signing on the cordova.tsauth object. Every method except isUserCanceled returns a Promise.

Capabilities

Passkeys (WebAuthn): registration, authentication, transaction signing, and cross-device approval
Native biometrics: Face ID, Touch ID, and Android BiometricPrompt
Device-bound PIN code with a two-phase commit
TOTP authenticator registration and code generation
Device key signing

Requirements

cordova-ios 8.0.0 or higher
cordova-android 12.0.0 or higher (14.0.1 or higher recommended). cordova-android 12 is the floor because the native biometric prompt needs a FragmentActivity, and that is the version where CordovaActivity became an AppCompatActivity. You do not need to modify MainActivity.
iOS 13.0 or higher, Xcode 16 or higher (Swift Package Manager must reach GitHub)
Android minSdk 24 (the SDK floor is API 21), compileSdk 35

Installation

cordova plugin add https://github.com/TransmitSecurity/cordova_ts_authentication_plugin.git#v1.0.0
cordova platform add ios android
cordova prepare ios android

Platform configuration

Set the deployment target to 13.0 or higher in config.xml:

<platform name="ios">
    <preference name="deployment-target" value="13.0" />
</platform>

Passkeys require an Associated Domains entitlement. The plugin cannot add this, because it needs your relying-party domain:

<platform name="ios">
    <config-file target="*/Entitlements-Debug.plist" parent="com.apple.developer.associated-domains">
        <array><string>webcredentials:your-domain.com</string></array>
    </config-file>
    <config-file target="*/Entitlements-Release.plist" parent="com.apple.developer.associated-domains">
        <array><string>webcredentials:your-domain.com</string></array>
    </config-file>
</platform>

The domain must also serve /.well-known/apple-app-site-association with a webcredentials entry for your app id. Without that file, passkey registration fails with invalidDomain. See the iOS WebAuthn quickstart for the associated-domain setup.

The plugin adds NSFaceIDUsageDescription with the string Used to authenticate you with Face ID. Override it in config.xml when you want different wording.

Xcode resolves the native SDK through Swift Package Manager on the first build. If it does not, use File → Packages → Resolve Package Versions.

This plugin does not use CocoaPods. cordova prepare removes the unused CocoaPods files that cordova-ios generates, so the iOS project stays on Swift Package Manager.

Credentials

initializeSDK() reads credentials from a native config file. initialize(clientId, options) takes them in JavaScript. Use one of the two.

Ship TransmitSecurity.plist as a resource:

<platform name="ios">
    <resource-file src="resources/ios/TransmitSecurity.plist" target="TransmitSecurity.plist" />
</platform>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>credentials</key>
    <dict>
        <key>baseUrl</key>
        <string>https://api.transmitsecurity.io/</string>
        <key>clientId</key>
        <string>YOUR_CLIENT_ID</string>
        <key>domain</key>
        <string>your-domain.com</string>
    </dict>
</dict>
</plist>

The configurationFile argument is the iOS plist basename. Android ignores it.

domain is the WebAuthn relying-party domain. baseUrl is the Mosaic API host for your region:

Region	Base URL
US	`https://api.transmitsecurity.io/`
EU	`https://api.eu.transmitsecurity.io/`
Canada	`https://api.ca.transmitsecurity.io/`
Australia	`https://api.au.transmitsecurity.io/`
Japan	`https://api.gasne1-ts01.transmitsecurity.io/`
Sandbox	`https://api.sbx.transmitsecurity.io/`
Custom domain	`https://<your-custom-domain>/` (see Custom domains)

Initialization

The cordova.tsauth object is available after the deviceready event.

document.addEventListener('deviceready', async function () {
  await cordova.tsauth.setLoggingEnabled(true);
  await cordova.tsauth.initializeSDK();

  if (await cordova.tsauth.isWebAuthnSupported()) {
    const { result } = await cordova.tsauth.registerWebAuthn('alice@example.com', 'Alice');
    // POST result to your backend to complete registration
  }
}, false);

Or initialize with explicit parameters. Set webAuthnApiPaths only when passkey ceremonies go through your own backend:

await cordova.tsauth.initialize('YOUR_CLIENT_ID', {
  baseUrl: 'https://api.transmitsecurity.io/',
  domain: 'your-domain.com',
  webAuthnApiPaths: {
    startRegistration: '/webauthn/register/start',
    startAuthentication: '/webauthn/authenticate/start',
  },
});

Next steps

Call the Authentication functions for passkeys, biometrics, PIN code, TOTP, and device-key signing.

This plugin is often used with the Orchestration SDK. When a journey reaches a passkey, biometrics, or TOTP step, create the credential here and send it back to the journey with submitClientResponse. For passkey registration, submit the encoded result as webauthn_encoded_result:

const { result } = await cordova.tsauth.registerWebAuthn(response.data.username);
await cordova.tsido.submitClientResponse('clientInput', { webauthn_encoded_result: result });

See journey steps for this step in a journey handler.