@kiauth/react-native-sdk

Three things, for React Native apps:

1. Verified Human — know the person signing up is a real, unique, Aadhaar-verified human. Not a bot, not a duplicate account.
2. Signup / Login — passwordless "Login with Kiauth". Opens the Kiauth app, the user approves with a biometric, you get the verified user back. No client secret needed — the SDK uses PKCE.
3. Session management + cross-app knowledge — the user sees every app they are signed into and can revoke any of them; your server is told when they do.

Backend: https://api.kiauth.com — pass it as baseUrl. The user must have the Kiauth app installed to approve the login.

Install

npm install @kiauth/react-native-sdk

Peer deps: react >= 18, react-native >= 0.70 (already in your app).

Recommended: install a secure random source so PKCE uses real entropy.

npm install react-native-get-random-values

// at the very top of your app entry point (index.js / App.tsx)
import 'react-native-get-random-values';

Without it the SDK warns and falls back to Math.random(), which weakens PKCE.

Usage

import { KiauthLoginButton, isProductionTrustworthy } from '@kiauth/react-native-sdk';

<KiauthLoginButton
  clientId="YOUR_CLIENT_ID"
  scopes={['name', 'email']}
  environment="production"
  baseUrl="https://api.kiauth.com"
  buttonText="Login with Kiauth"
  onSuccess={(user) => {
    // ❌ Not enough — `kiauth_verified` is ALSO true for Kiauth's test identities.
    // if (user.kiauth_verified) { ... }

    // ✅ The check a production app should make:
    if (!isProductionTrustworthy(user)) return showError('Could not verify identity.');

    // user.userToken — stable + pairwise. The SAME human always maps to this token in
    //                  YOUR app, and to a different one in every other app.
    createAccount({ kiauthUserToken: user.userToken, name: user.name, email: user.email });
  }}
  onError={(err) => console.warn(err.message)}
/>

Or use the hook directly:

import { useKiauth } from '@kiauth/react-native-sdk';

const { startLogin, loading } = useKiauth();

const user = await startLogin({
  clientId: 'YOUR_CLIENT_ID',
  scopes: ['name', 'email'],
  environment: 'production',
  baseUrl: 'https://api.kiauth.com'
});

isProductionTrustworthy(user) is exactly user.kiauth_verified && user.assurance_level === 'aadhaar' && !user.is_test_identity.

The KiauthUser object

| Field | Type | Meaning | |---|---|---| | kiauth_verified | boolean | Kiauth ran an identity check and it passed. Also true for test identities. | | verified | boolean | Alias of kiauth_verified. Both are always present. | | identity_verified | boolean | The durable fact that this human completed Aadhaar verification. Never decays. | | assurance_level | 'aadhaar' \| 'human' \| 'test' \| 'none' | How strong the check was. | | is_test_identity | boolean | TRUE for a fabricated identity from Kiauth's test mode. Reject in production. | | uniqueness | 'one_account_per_human' | Kiauth's guarantee. | | userToken | string | Stable, pairwise per (human, your app). Key your account on it. | | verified_at | string | null | ISO timestamp of the identity check. | | verification_expires_at | string | null | When Kiauth will ask them to renew. | | assurance_age_days | number | null | How old the check is, in whole days. | | assurance_fresh | boolean | Whether it is inside Kiauth's current freshness window. |

Re-verification is Kiauth's job, not yours. Kiauth periodically re-checks each human; that cadence is a Kiauth↔user relationship. You are never forced to make a user re-verify because our clock ran out.

Config

| Field | Required | Notes | |---|---|---| | clientId | yes | From your app in the Kiauth dev portal | | scopes | yes | Subset of name, email, dob, gender, phone | | environment | optional | Defaults to 'production' | | baseUrl | recommended | Backend URL. Overrides the env default. /api/v1 appended automatically. | | clientSecret | no — do not use | Anything in a mobile binary can be extracted from the APK/IPA. The SDK uses PKCE and needs no secret. Supplying one logs a warning. |

How the login works

The SDK opens the Kiauth authenticator app (kiauth://auth?sid=...) and then polls the backend for approval, so no return deep link or custom URL scheme is required in your app. If the Kiauth app is not installed, the SDK detects it and sends the user to the App/Play Store.

It then completes the authorization-code exchange itself using PKCE (RFC 7636) — a one-time code_verifier proves the SDK started the flow, so no secret ever ships in your binary.

Session management

Reporting non-Kiauth logins and ending sessions requires your clientSecret, so those calls belong on your server, not in the app. See @kiauth/web-sdk — reportSession, reportSessionByEmail, reportBatchSessions, logout — or call the REST API directly.

Handle these webhooks server-side: SESSION_CREATED, SESSION_REVOKED, PERMISSION_REVOKED.

Changelog

2.0.0 — breaking, and you should upgrade

• Fixed (security): when no clientSecret was supplied — the recommended configuration — startLogin() returned a fabricated user: kiauth_verified was hardcoded true regardless of whether the human was verified at all, and userToken was code_<authCode>, a value that changed on every login. An app trusting the flag was trusting nothing; an app keying accounts on that token created a new account on every sign-in. Both are gone.
• Added: real PKCE (RFC 7636) support. The no-secret path now performs a genuine authorization-code exchange and returns the real, graded user. React Native has no Web Crypto, so SHA-256 is implemented in-package and verified against Node's crypto.
• Added: graded identity claims — assurance_level, is_test_identity, identity_verified, assurance_age_days, assurance_fresh, uniqueness.
• Added: isProductionTrustworthy(user) — the check a production app should make.
• Hardened: every response is normalized and fails closed. A missing or unrecognised field grades as unverified rather than reaching your if as undefined.
• Changed: KiauthApi.exchangeToken(code, clientId, credentials) now takes { codeVerifier?, clientSecret? } instead of a bare clientSecret string.
• Removed: the undocumented user.code property. It only ever existed on the fabricated object.

Migration: delete clientSecret from your KiauthLoginButton / startLogin config, add react-native-get-random-values, and gate on isProductionTrustworthy(user) instead of user.kiauth_verified.

1.0.0

• Initial release.