cr3dentials_zktls

Verify your users' accounts from a Flutter app with the Cr3dentials zkTLS SDK: Zktls.configure once, at launch, and Zktls.verify per user. The SDK shows its own screens, opens each platform's sign-in page, and has each result read and signed by a Cr3dentials attester; your server gets the results in signed webhooks, never through your app. This plugin is a thin bridge: the native SDK does the work, and Dart drives it through one API on both platforms, generated with Pigeon from pigeons/messages.dart.

iOS Android
Minimum OS iOS 15.0 Android 7.0 (API 24)
The native SDK ZktlsSDK 2.2.0 or later, from zktls-sdk-releases (Swift Package Manager or CocoaPods) xyz.cr3dentials:zktls-sdk:2.2.0, from Maven Central

The SDK's guide holds the details this page links to: start with its overview.

Requirements

Dart 3.13 or later. Android 7.0 (API 24) or later. iOS 15.0 or later.

Install

flutter pub add cr3dentials_zktls

Android needs nothing more: Gradle fetches the SDK from Maven Central. On iOS, with Swift Package Manager, Flutter's default, the plugin's package brings the SDK. If your app uses CocoaPods instead, the SDK's releases repository is its own CocoaPods spec source, and CocoaPods takes a pod from the first source that has it, so list it first in your Podfile:

source 'https://github.com/Cr3dentials/zktls-sdk-releases.git'
source 'https://cdn.cocoapods.org/'

What you need from us

Your app's publishable key, zk_live_… or zk_test_…, and the platform ids you verify. A test key works on simulators and emulators and runs only the demo platform, zktls-demo (any user name, the password demo). The SDK's guide explains both (overview).

Verify a user

import 'package:cr3dentials_zktls/cr3dentials_zktls.dart';
import 'package:flutter/services.dart';

// Once, when your app starts.
await Zktls.configure('zk_test_…');

// Per user. The reference is a value your server already knows, such as a user or order id: every
// webhook carries it.
try {
  final outcome = await Zktls.verify(['zktls-demo'], 'order_8f3k2');
  for (final p in outcome.platforms) {
    print('${p.platform} ${p.status} ${p.reason}'); // done, failed or notStarted
  }
} on PlatformException catch (e) {
  if (sdkErrorCodeOf(e) == SdkErrorCode.refused) {
    // The verification did not start; the SDK has already shown the user why.
    print('${refusalOf(e)} ${e.message}'); // such as device_not_verified
  }
}

verify returns once the user leaves the flow, with a VerifyOutcome: its verificationId and, per platform, its status and, for a failure, a reason. It carries no data from the platform: your server gets one signed platform.finished webhook per platform the user started, and one verification.finished when every platform has ended (webhooks). Zktls.verifyToken(token) runs the platforms and the reference your server set with POST /partner/verification-tokens.

On Android, verify shows its screens over the current activity, which must stay in front until it returns. On iOS, over the key window's top-most view controller.

The look of the SDK's screens

configure takes a ZktlsTheme and the screens' words:

await Zktls.configure(
  'zk_live_…',
  theme: const ZktlsTheme(accent: '#1E66F5', background: '#FFFFFF', text: '#111111', logo: 'brand_logo'),
  strings: {'list.title': 'Verify your income'}, // any screen string, by key
);

ZktlsTheme is the native SDK's name, and does not clash with Material's Theme. Colors are exactly #RRGGBB or #AARRGGBB (alpha first), with hex digits in either case; color names and other forms are refused. logo names an image in your app: an Android drawable, an iOS asset. A field you leave null keeps the SDK's default. The platform list and the consent screens are in Cr3dentials' colors, with your theme's logo at the top; your colors apply to the refusal screen. The string keys are the SDK's own, such as list.title or consent.agree, the same on both platforms; keep the words in braces, such as {terms} and {privacy} in consent.agree, which the SDK fills in (iOS, Android). Each value in strings is a String, as its type requires.

A color in another form makes configure throw a PlatformException with the code InvalidArgument and a message naming it, such as theme.accent must be #RRGGBB or #AARRGGBB, on both platforms. The SDK's configuration is then left as it was.

Prove a fact

The SDK's proof flow is here too, for a policy and profile we set up with you: ZktlsClient.create(config), then login, capture, prove and claim. The user's account data never leaves the phone; the claim carries only the proven outputs, signed by the verifier.

final client = await ZktlsClient.create(config); // a SessionConfig, per session
final progress = client.onProgress().listen((e) => setProgress(e.phase, e.percent));
try {
  await client.login(); // the disclosure, then the page
  await client.capture();
  final report = await client.prove();
  if (report.accepted) {
    final claim = await client.claim(); // verified against the trust bundle
    await send(claim.encoded); // your backend verifies it again
  }
} finally {
  await progress.cancel();
  await client.dispose(); // every path
}

SessionConfig has the native SDK's fields and rules (field table), and your backend verifies the claim itself (verifying a claim).

Things to know

  • One verification at a time. A verify called while another runs waits for it to finish.
  • Background. verify keeps itself alive when the user leaves your app. For a proof session, the plugin does what the SDK's guides ask of a native app: after login it follows Wi-Fi and cellular handovers and keeps the session alive, with a short foreground service on Android and background time on iOS.
  • The notification. On Android the foreground service shows a notification reading "Verifying". Define zktls_session_notification_title, zktls_session_channel_name and the drawable zktls_session_notification_icon in your app's resources to translate or rebrand it.
  • The disclosure. A proof session's login() shows the SDK's standard disclosure before the page. Pass login(Disclosure(title: …, message: …, accept: …, decline: …)) to translate it; a field you leave null keeps the standard text.
  • Errors. A failed call throws a PlatformException whose code is the SDK's error name, such as Refused (errors); sdkErrorCodeOf(e) turns it into an SdkErrorCode. For a refusal, refusalOf(e) gives the reason, such as device_not_verified or app_key_invalid. For Transport, Policy and Refused, message carries the SDK's text. InvalidArgument is the plugin's own: configure was given a theme color it cannot use, which message names. Internal is a fault inside the SDK that was not one of its errors: report it.
  • Logging. Never log your app key in production builds, or a SessionConfig: it holds the app credential.

Before you submit

Work through the SDK's release checklist: your app's registration with us, the device checks, privacy answers, and a test account for review.

The example app

example/ runs on both platforms. Its "Test bridge" button exercises the proof-flow round-trips that need no live backend. Its "Verify" button runs verify with the app key passed at run time, so none is kept in source:

flutter run --dart-define=ZKTLS_APP_KEY=zk_test_…

Versions

Releases follow Semantic Versioning. Version 2 of the plugin wraps version 2 of the SDK: it depends on 2.2.0 or later, within 2.x.

License

Apache-2.0. The SDK's own license and the open-source notices of its compiled core are in the zktls-sdk-releases repository.

Libraries

cr3dentials_zktls