Skip to main content
This page takes you from an empty project to your first test webhook. It uses your test key and the demo platform zktls-demo, so you need no real account anywhere, and the iOS Simulator is enough.

Before you start

  • Your test key (zk_test_…) from Register your app.
  • A webhook endpoint that checks the signature, and its signing secret. Webhooks has the code for Node and Python. The URL must be public HTTPS. To try it on your own machine, run that code and expose it with a tunnel, for example cloudflared tunnel --url http://localhost:3000, then set the webhook you registered to the tunnel’s URL plus the sample’s path, for example https://<name>.trycloudflare.com/webhooks/cr3dentials. Change that webhook’s URL rather than adding a new one: its signing secret stays the same. A quick tunnel gets a new URL each time it starts, so update the webhook after a restart.
  • iOS 14.0 or later. Devices are arm64. The simulator slice covers both Apple silicon and Intel Macs.
  • Xcode 26 to upload to the App Store. The SDK is built and tested with Xcode 26.3 and declares Swift tools 5.9.
The SDK needs no Info.plist key, and no entitlement for TestFlight and App Store builds. App Attest works from the bundle ID and Team ID you registered with us.

1. Install

In Xcode, choose File → Add Package Dependencies and enter https://github.com/Cr3dentials/zktls-sdk-releases. Add the product ZktlsSDK to your app target.In a Package.swift:
The xcframework is signed with the Cr3dentials Apple Distribution certificate, Team ID R8287QD4F7. To check it, run codesign -dv ZktlsSDKFFI.xcframework.

2. Configure

Call Zktls.configure once, when your app launches:
The app key is publishable, so it can live in your code or your build settings. Use the test key in debug builds and the live key in release builds.

3. Verify

Call Zktls.verify with the platform ids and your reference. It runs on the main actor, presents the SDK’s screens over your app, and returns when the user leaves the flow:
The outcome tells your app only how each platform ended. The results go to your server, by webhook. Don’t wait in the app for them: show your own next step as soon as verify returns. The fields are in The outcome, and the refusal codes are in Errors. To finish later, call verify again with the platforms that were not started. It is a new verification, and you can pass the same reference:
To start from your server, have your server create a token with POST /partner/verification-tokens and pass it to the app. The token carries the platforms and the reference:

4. Test with zktls-demo

1

Run your app

Run it on the Simulator or a device, with your test key, and tap the button that calls verify(["zktls-demo"], reference: …).
2

Go through the screens

Tap Start on the intro, then Continue on the sign-in notice.
3

Sign in to the demo bank

Enter any user name and the password demo, which the page shows.
4

See the outcome

The SDK hands the run to an attester and shows All done. verify returns with zktls-demo as .done.
5

Get the webhooks

Within seconds, your endpoint receives a platform.finished with "test": true and the demo bank’s latest transfer, and a verification.finished, in either order. Both carry your reference.
Zktls.configure hasn’t run before verify. Call it at launch.
Read the code you caught in Errors. With a test key, platform_unavailable means a platform other than zktls-demo.
Check that your webhook is Active in the Partner Portal and returns a 2xx, and look under Webhooks → Logs. If your endpoint answers 4xx because the signature check fails, check the secret and that you sign the raw body (Webhooks).

5. Theme and strings

The layout of the screens is fixed. You set the colours, the logo and the wording, when you configure:
ZktlsTheme() with no arguments keeps the SDK’s own look. English ships built in. Override any string by its key, for example with your own translations. Words in braces are filled in by the SDK, so keep them in your text:

Things to know

  • The screens. The SDK presents them with UIKit, over the top-most view controller of your key window. SwiftUI apps need nothing extra.
  • Stopping. Not now on the intro, Stop here between platforms, Cancel on the sign-in notice or closing a sign-in page each end the flow. The platform the user was on, and every later one, are not started.
  • Where the page may go. The sign-in page stays on the platform’s domains and on the third-party sign-in providers the platform uses. If the user follows a link anywhere else, that platform ends as failed.
  • Your app’s web data. Each run has its own non-persistent web data store, so your own WebViews and cookies are untouched.
  • Background time. The SDK holds background time during each hand-off. You add no lifecycle code.
  • Logging. Log the verificationId, the statuses, the reasons and the refusal codes. Your Partner API key and webhook secret never belong in the app at all.

Before you submit

  • Live keys need App Attest, on a real device. The Simulator has no App Attest, so a live key there shows “This device can’t be verified” and throws device_not_verified. Builds you run from Xcode, and ad hoc builds, use App Attest’s development environment by default, which live keys refuse unless you add the App Attest capability with its environment set to production, or we allow development builds for your app (ask us; we turn it off before your release). TestFlight and App Store builds always use production. Develop with the test key, and try the live key with a TestFlight build on an iPhone or iPad.
  • Your registered app. The build’s bundle ID and Team ID must be the ones you registered with us.
  • The live key in release builds. A test key in a release build runs only zktls-demo.
  • App Privacy. The SDK includes its privacy manifest. It declares User ID, Device ID (the install’s id, which Cr3dentials keeps with each verification) and Coarse Location, all linked to the user, not used for tracking, and for App Functionality. Add these to your App Privacy answers, along with the data types your verification’s results hold: each platform’s result is collected, because Cr3dentials keeps it with the verification and sends it to your server.
Work through the release checklist for export compliance and App Review notes.