@kiavi/kiavi-react-native

Kiavi authentication for React Native apps (Expo and bare React Native, iOS and Android).

Speaks the same /api/auth/exchange/* wire protocol as @kiavi/kiavi-browser. PKCE only — no client secrets. Refresh tokens are stored in the OS keychain (iOS Keychain / Android Keystore) via expo-secure-store.

Install

pnpm add @kiavi/kiavi-react-native expo-auth-session expo-secure-store expo-crypto

expo-auth-session brings expo-web-browser in transitively; if you have a bare workflow that pins peer deps, install it explicitly too.

After install, the package automatically writes its version-pinned integration guide to .kiavi/kiavi-react-native.md and adds a reference block to your repo's AGENTS.md (or CLAUDE.md). If your package manager blocks dependency scripts, run npx kiavi-react-native init for a manual refresh and approval guidance. See AI agent docs for the full picture.

Configure your app's URL scheme

The SDK discovers your app slug from the auth server and derives its redirect URI from it. An app with slug acme redirects to acme://auth, and the auth server only allows that scheme prefix for its derived acme-native client. Add the matching scheme to app.json:

{
  "expo": {
    "scheme": "acme",
    "ios": {
      "bundleIdentifier": "com.acme.app"
    },
    "android": {
      "package": "com.acme.app"
    }
  }
}

If you need a different scheme or a Universal Link / App Link, pass redirectUri explicitly to the constructor. Whatever you pass must match an entry in the client's allowed_origins (configured in the Kiavi management UI).

Initialize

import { KiaviClient } from '@kiavi/kiavi-react-native'

export const kiavi = new KiaviClient({
  authBaseUrl: 'https://auth.acme.kiavi.eu',
  // redirectUri: 'acme://auth' — derived automatically
})

Sign in

import { Button } from 'react-native'
import { kiavi } from '@/lib/kiavi'
import { useRouter } from 'expo-router'

export default function SignInScreen() {
  const router = useRouter()
  return (
    <Button
      title='Sign in'
      onPress={async () => {
        const session = await kiavi.authenticate()
        router.replace('/home')
      }}
    />
  )
}

authenticate() is idempotent: if a session is already live or silently refreshable from secure storage, it returns immediately. Otherwise it opens the system browser (SFSafariViewController on iOS, Custom Tabs on Android) and resolves once the user returns.

Call your API

const token = await kiavi.getAccessToken()
const res = await fetch('https://api.acme.com/me', {
  headers: { Authorization: `Bearer ${token}` },
})

getAccessToken() refreshes automatically when the access token has less than 30 seconds of life left. Concurrent callers share one in-flight refresh — there is no need to debounce yourself.

If there is no session and refresh fails, it throws KiaviSessionExpiredError. Catch that and call authenticate() to start a new sign-in flow.

React to session changes

useEffect(() => {
  return kiavi.onAuthStateChange((session) => {
    if (!session) router.replace('/sign-in')
  })
}, [])

The listener fires on every successful sign-in, every refresh, every sign-out, and every refresh failure that clears the session (for example, when the user revokes this device from another device). It does NOT fire synchronously on subscription — call getSession() first if you need the current state.

Sign out

await kiavi.signOut()

Revokes the refresh token server-side, wipes secure storage, and notifies listeners. There is no browser redirect on mobile — handle navigation yourself.

Errors

import { KiaviAuthError, KiaviSessionExpiredError } from '@kiavi/kiavi-react-native'

try {
  const token = await kiavi.getAccessToken()
} catch (err) {
  if (err instanceof KiaviSessionExpiredError) {
    // No valid session and refresh failed — kick the user to sign-in.
    await kiavi.authenticate()
    return
  }
  if (err instanceof KiaviAuthError) {
    // err.code: 'rate_limited' | 'invalid_request' | 'unauthenticated'
    //         | 'server_error' | 'network_error' | 'unknown'
    // err.status, err.retryAfterSeconds
  }
}

Network errors (offline, DNS failure) surface as KiaviAuthError with code: 'network_error' and status: 0. They never wipe the user's saved refresh token — only an unauthenticated (401) response from /refresh does that, since it means the chain has been server-side revoked.

Bare React Native (non-Expo) notes

expo-auth-session, expo-secure-store, expo-crypto, and expo-web-browser all support bare RN via expo install. Follow each package's installation steps; no other changes are needed.

Debug logging

new KiaviClient({
  authBaseUrl: '...',
  debug: true, // logs to console
  // or pass a function: debug: (entry) => myLogger.log(entry)
})