In June 2026, forty organizations — government ministries, private companies, and non-profits — pushed 160 new services into Tawakkalna in a single month. That is not a milestone announcement; it is the current deployment pace. The Saudi national super app now hosts more than 1,000 government services and has more than 34 million registered users. If you are building a product for the Saudi market and you are not considering a Tawakkalna integration, you are choosing to ignore the largest verified-identity distribution channel in the country.
This guide is for developers who need to understand how the Partners program works, which SDK to use, what data is available, and where most integrations break before they ship.
Two Integration Paths
SDAIA (the Saudi Data and AI Authority) offers two distinct routes into the Tawakkalna ecosystem:
Partner Portal (REST API) — for organizations that want to surface their own hosted services inside the Tawakkalna app. Think of this as publishing a service card in the national app, where users discover it alongside ministry services and tap through to your system. Your backend handles the logic; Tawakkalna provides the distribution.
Mini-App SDK (Flutter/Web) — for organizations that want to embed a full interactive experience inside Tawakkalna. Your app runs as a web view within the native shell, but has JavaScript-bridge access to the device's verified Tawakkalna session. This means you get user identity, documents, and health data without building your own authentication layer.
The two paths are not mutually exclusive. Most mature integrations use the REST API for data exchange and the Mini-App SDK for the interactive user flow.
Mini-App SDK: Setup
The Flutter SDK is published on pub.dev as tawakkalna_sdk_flutter. The current release is 0.0.5-alpha.5. It works as a web-to-native bridge: your Flutter app compiles to HTML and JS, runs inside a WebView in the Tawakkalna host app, and calls native Tawakkalna methods via a JavaScript interop layer.
pubspec.yaml
dependencies:
tawakkalna_sdk_flutter: ^0.0.5-alpha.5You need to add a different JS bridge file to web/index.html depending on the environment:
- Development:
twkhelper_mock.js— returns realistic mock data so you can build and test without a real device session - Production:
twkhelper.js— connects to verified user data; works only inside the actual Tawakkalna app
Basic initialization:
final twk = TwkHelper();
final fullName = await twk.getUserFullName();If you initialize TwkHelper() outside the Tawakkalna shell — in a standalone Flutter build, for instance — the production bridge throws immediately. The development mock silently returns sample data, which is the only way to run local unit tests.
What Data the SDK Exposes
The V1 API surface covers more than 45 methods across six categories:
Identity and Personal Data
- National ID number, full name, gender, birth date, nationality
Documents
- Passport number and expiry date, Iqama number and expiry date (for residents)
Health
- Blood type, disability status (useful for accommodation and accessibility workflows)
Family
- Family members list with filtering options, sponsor information
Vehicles
- Registered vehicle details, outstanding traffic violations
Location and Device
- GPS coordinates, national address, gallery/camera access, notification permissions
Authentication
The SDK issues session tokens via twk.generateToken(). Biometric authentication is available via twk.authenticateBiometric() — this calls the Tawakkalna app's built-in fingerprint or face prompt, not the device OS unlock. The credential is tied to the user's verified Tawakkalna identity. That distinction matters for compliance: it is a higher-trust signal than a device PIN.
V2 adds five additional methods not yet fully documented in the public portal at the time of writing.
What Saudi Businesses Build With This
Customer KYC — A fintech or insurance company collects verified national ID and health data in under a minute rather than running a manual document scan. No separate integration with Yakeen or Nafath is required for basic identity — Tawakkalna's session is the trust anchor. For more rigorous NIC verification against the national identity database, see the Yakeen, Nafath, and Wathq identity verification guide.
Employee onboarding — HR teams verify Iqama status, expiry date, and sponsorship data at the point of application. When combined with Qiwa, this eliminates one of the most common manual checks in the onboarding pipeline. The Qiwa integration and Nitaqat compliance guide covers the Qiwa side of that connection.
E-commerce identity verification — Marketplaces selling age-restricted or licensed categories use Tawakkalna identity tokens as their verification gate rather than building a separate document upload flow. The user taps once and the token is issued; no scan, no manual review.
Vehicle fleet management — Logistics companies pull vehicle registration and outstanding violation data for their drivers in one call, replacing a manual Absher lookup per employee. On the entity type distinction that governs which Saudi workforce platform a company can use, see Absher Business vs Muqeem.
Business verification overlay — For B2B workflows that need to confirm the user is acting on behalf of a registered entity, a Maroof token can be layered on top of the personal Tawakkalna identity. The Maroof and Wathq API guide documents how that secondary check is structured.
Three Integration Mistakes That Delay Go-Live
1. Building against mock data all the way through QA
The mock bridge returns the same sample data set on every call. Developers test the happy path and miss edge cases: users with expired Iqamas, users who have not granted the required permission (camera, location), users without a verified email address. Plan at least one sprint of user acceptance testing inside the real Tawakkalna sandbox environment before submitting for partner approval.
2. Treating biometric auth as a standalone primary factor
Biometric authentication via the SDK confirms that the device user matches the Tawakkalna account. It does not confirm liveness or re-verify against the national identity database. For high-risk transactions — credit applications, contract signing, large payment authorization — a secondary verification step is required. Typically this is a Nafath OTP or a Maroof business verification. Skipping this and discovering it at the SDAIA security review adds six to eight weeks to the approval timeline.
3. Skipping the Partner Portal approval step until after build
The Mini-App SDK can be built and tested end-to-end without a formal partnership agreement. Production deployment requires SDAIA approval through the Partner Portal. Applications that arrive at this gate after eight weeks of development — rather than at the start — regularly face a two-month review cycle that stalls the launch and frustrates clients who have already been shown a working demo.
Submit the partnership application at the same time you write your first line of SDK code.
Registration Requirements
Becoming a Tawakkalna partner requires four things:
- A commercial registration (CR) valid in Saudi Arabia
- An active data processing policy compliant with the National Cybersecurity Authority (NCA) guidelines
- A technical contact with verified access to the SDAIA developer portal
- Submission of the service brief and integration architecture document for SDAIA review
Private-sector organizations that have already cleared the Maroof verification step tend to move faster through this process because the entity validation has already been completed.
The Bigger Picture
Tawakkalna is no longer the health pass app it was during the pandemic. Saudi Arabia is using it as a national identity and services layer — a single authenticated shell through which 34 million users interact with government ministries, private businesses, and non-profits. The 160 services added in June 2026 alone show the pace has not plateaued; if anything, private-sector adoption is accelerating.
The developer SERP for Tawakkalna integration is essentially empty. The official portal exists but carries no independent implementation guides. Teams that ship a working integration and document the lessons learned publicly build category authority here before the space matures.
If you are planning a Saudi-market product that requires verified identity, health status, or document verification, the integration architecture decision needs to happen at the start of the project — not after you have already built a parallel KYC stack that will need to be unwound.
Ready to scope your Tawakkalna integration? Our team has mapped the full Saudi government API stack — from ZATCA to Qiwa to SDAIA. Contact Noqta for a no-pitch technical review of your integration plan before the design phase is over.