dianaKhortiuk-frontegg · Aug 19, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -1,15 +1,43 @@
-# Frontegg React Native SDK
-![Frontegg_React Native_SDK](/images/frontegg-react-native.png)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/frontegg/frontegg-react-native/master/images/frontegg-react-native.png" alt="Frontegg React Native SDK" width="640" />
+</p>
 
-Welcome to the official **Frontegg React Native SDK** — your all-in-one solution for
-integrating authentication and user management into your React Native mobile
-app. [Frontegg](https://frontegg.com/) is a self-served user management platform, built for modern
-SaaS applications. Easily implement authentication, SSO, RBAC, multi-tenancy, and more — all from a
-single SDK.
+<h1 align="center">Frontegg React Native SDK</h1>
 
-## 📦 Peer Dependencies
+<p align="center">
+  <strong>Authentication and user management for your React Native app — one package, both platforms.</strong>
+</p>
 
-Install the required peer dependencies in your app:
+<p align="center">
+  <a href="https://www.npmjs.com/package/@frontegg/react-native"><img src="https://img.shields.io/npm/v/@frontegg/react-native?label=npm&color=6c47ff" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/iOS-14%2B-lightgrey" alt="iOS 14+" />
+  <img src="https://img.shields.io/badge/Android-API%2026%2B-3ddc84" alt="Android API 26+" />
+  <img src="https://img.shields.io/badge/React%20Native-0.63%2B-61dafb" alt="React Native 0.63+" />
+  <a href="https://github.com/frontegg/frontegg-react-native/blob/master/LICENSE"><img src="https://img.shields.io/github/license/frontegg/frontegg-react-native?color=blue" alt="Licence" /></a>
+</p>
+
+---
+
+[Frontegg](https://frontegg.com/) is a self-served user management platform for modern SaaS
+applications. Drop this SDK in and your app gets a production login screen, a live session, and a
+user object — without you writing an auth flow or touching a token.
+
+| | |
+| --- | --- |
+| **Hosted or embedded login** | Frontegg's login box, or your own UI on top of the API |
+| **Every method your tenants need** | Email, social, SSO, magic link, passkeys, MFA and step-up |
+| **Sessions that stay alive** | Tokens refresh in the background, on both platforms |
+| **Built for multi-tenant SaaS** | Multi-tenancy, RBAC, entitlements and multi-region support |
+
+---
+
+## Install
+
+```sh
+npm install @frontegg/react-native
+```
+
+Then the peer dependencies:
 
 ```sh
 # Expo
@@ -19,51 +47,87 @@ npx expo install @react-native-async-storage/async-storage @react-navigation/nat
 npm install @react-native-async-storage/async-storage @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context
 ```
 
-## 📚 Documentation
+**Requirements:** React Native 0.63+ · iOS deployment target 14+ · Android API 26+ with JDK 17 and
+AGP 7.4+. Passkeys additionally need iOS 15+ and Chrome Custom Tabs on Android.
 
-This repository includes:
+## Quick start
 
-- A [Get Started](https://react-native-guide.frontegg.com/#/getting-started) guide for quick integration
-- A [Setup Guide](https://react-native-guide.frontegg.com/#/setup) with detailed setup instructions
-- [Usage Examples](https://react-native-guide.frontegg.com/#/usage) with common implementation patterns
-- [Advanced Topics](https://react-native-guide.frontegg.com/#/advanced) for complex integration scenarReact Native
-- A [Embedded](https://github.com/frontegg/frontegg-react-native/tree/master/example) example projects to help you get started quickly
+**1 · Allow the redirect URLs.** In the Frontegg Portal, under **[ENVIRONMENT] → Authentication →
+Login method**, turn hosted login on and add the shared URL plus one per platform:
 
-For full documentation, visit the Frontegg Developer Portal:
-🔗 [https://developers.frontegg.com](https://developers.frontegg.com)
+```
+{{FRONTEGG_BASE_URL}}/oauth/authorize
 
----
+# iOS
+{{IOS_BUNDLE_IDENTIFIER}}://{{FRONTEGG_BASE_URL}}/ios/oauth/callback
 
-## 🔐 Native SDK versions
+# Android
+{{ANDROID_PACKAGE_NAME}}://{{FRONTEGG_BASE_URL}}/android/oauth/callback
+https://{{FRONTEGG_BASE_URL}}/oauth/account/redirect/android/{{ANDROID_PACKAGE_NAME}}
+```
 
-The React Native wrapper depends on the underlying native SDKs:
+**2 · Configure the native projects.** iOS reads a `Frontegg.plist`; Android takes its domain and
+client ID from `build.gradle`. Both are covered step by step in the
+[Setup guide](https://react-native-guide.frontegg.com/#/setup) — this is the one part that is not
+JavaScript, and it differs per platform.
+
+**3 · Wrap your app.**
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { FronteggWrapper } from '@frontegg/react-native';
+
+export default function App() {
+  return (
+    <FronteggWrapper>
+      <NavigationContainer>
+        {/* your navigator */}
+      </NavigationContainer>
+    </FronteggWrapper>
+  );
+}
+```
 
-- On **Android**, the plugin and example app use `com.frontegg.sdk:android:1.3.35`.
-- On **iOS**, the plugin depends on `FronteggSwift` **1.3.11** via CocoaPods.
+**4 · Read the authentication state** anywhere below it.
 
-After upgrading, run `pod install` in your iOS project and rebuild both platforms.
+```tsx
+import { View, Button } from 'react-native';
+import { useAuth, login } from '@frontegg/react-native';
 
----
+export function MyScreen() {
+  const { isAuthenticated } = useAuth();
 
-## 🔐 Native SDK versions
+  return (
+    <View>
+      {isAuthenticated ? <Profile /> : <Button title="Login" onPress={login} />}
+    </View>
+  );
+}
+```
 
-The React Native wrapper depends on the underlying native SDKs:
+## Documentation
 
-- On **Android**, the plugin and example app use `com.frontegg.sdk:android:1.3.35`.
-- On **iOS**, the plugin depends on `FronteggSwift` **1.3.11** via CocoaPods.
+| Guide | What it covers |
+| --- | --- |
+| [Get Started](https://react-native-guide.frontegg.com/#/getting-started) | Requirements, environment prep, installation |
+| [Setup](https://react-native-guide.frontegg.com/#/setup) | iOS and Android native configuration |
+| [Usage Examples](https://react-native-guide.frontegg.com/#/usage) | Hooks, login flows, error handling |
+| [API Reference](https://react-native-guide.frontegg.com/#/api) | Every method, hook and type the SDK exports |
+| [Advanced Topics](https://react-native-guide.frontegg.com/#/advanced) | Complex integration scenarios |
 
-After upgrading, run `pod install` in your iOS project and rebuild both platforms.
+Full platform documentation lives at [developers.frontegg.com](https://developers.frontegg.com).
 
----
+## Example app
 
-## 🧑‍💻 Getting Started with Frontegg
+A complete integration you can run:
+[example](https://github.com/frontegg/frontegg-react-native/tree/master/example).
 
-Don't have a Frontegg account yet?
-Sign up here → [https://portal.us.frontegg.com/signup](https://portal.us.frontegg.com/signup)
+## Support
 
----
+No Frontegg account yet? [Sign up free](https://portal.us.frontegg.com/signup).
 
-## 💬 Support
+Questions, or something broken? Reach the team at
+[support.frontegg.com](https://support.frontegg.com/frontegg/directories) or
+[open an issue](https://github.com/frontegg/frontegg-react-native/issues).
 
-Need help? Our team is here for you:
-[https://support.frontegg.com/frontegg/directories](https://support.frontegg.com/frontegg/directories)
+Licensed under the [LICENSE](https://github.com/frontegg/frontegg-react-native/blob/master/LICENSE) in this repository.
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,157 @@
+# Frontegg React Native API Reference
+
+Everything below is exported from `@frontegg/react-native`.
+
+```tsx
+import { FronteggWrapper, useAuth, login, logout } from '@frontegg/react-native';
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `FronteggWrapper` | Wraps your app and initialises the SDK. Everything below it can call `useAuth()`. Takes only `children`. |
+
+## Hooks
+
+### `useAuth()`
+
+Returns the current `FronteggState`. Re-renders on every change — sign-in, sign-out, token refresh.
+
+```tsx
+const { isAuthenticated, user, isLoading } = useAuth();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isAuthenticated` | `boolean` | Whether a user is signed in. |
+| `user` | `User \| null` | The signed-in user, including `tenants` and `activeTenant`. |
+| `accessToken` | `string \| null` | Current access token. |
+| `refreshToken` | `string \| null` | Current refresh token. |
+| `refreshingToken` | `boolean` | A token refresh is in flight. |
+| `isLoading` | `boolean` | An auth operation is in progress. |
+| `initializing` | `boolean` | The SDK has not finished starting up. |
+| `showLoader` | `boolean` | Convenience flag for whether to render a loading state. |
+
+## Authentication
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `login` | `loginHint?: string` | `Promise<void>` | Opens the login flow. `loginHint` pre-fills the identifier field. Resolves when login completes; rejects with a `FronteggLoginError`. |
+| `logout` | None | `Promise<void>` | Signs the user out and clears stored credentials. |
+| `loginWithPasskeys` | None | `Promise<void>` | Signs in with a passkey. Needs iOS 15+ or Android API 26+. |
+| `registerPasskeys` | None | `Promise<void>` | Registers a passkey for the signed-in user. |
+| `refreshToken` | None | `Promise<void>` | Forces a token refresh. The SDK also refreshes on its own in the background. |
+| `requestAuthorize` | `refreshToken: string`<br>`deviceTokenCookie?: string` | `Promise<void>` | Establishes a session from an existing refresh token, without opening the login flow. |
+
+### Social and direct login
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `directLoginAction` | `type: string`<br>`data: string`<br>`ephemeralSession = true`<br>`additionalQueryParams?: Record<string, string>` | `Promise<void>` | Starts a specific login action, such as a named social provider, inside the embedded flow. |
+
+> `ephemeralSession` and `additionalQueryParams` are honoured on **iOS only**. Android's native
+> `directLoginAction` does not accept them yet and ignores them. `ephemeralSession` is inherently
+> iOS-specific — it maps to the `ASWebAuthenticationSession` browser session.
+
+## Step-up authentication
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `isSteppedUp` | `maxAge?: number` (seconds) | `Promise<boolean>` | Whether the session is currently stepped up. Omit `maxAge` for no age limit. |
+| `stepUp` | `maxAge?: number` (seconds) | `Promise<void>` | Starts step-up authentication (MFA or re-auth). |
+
+## Tenants
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `switchTenant` | `tenantId: string` | `Promise<void>` | Switches the active tenant. IDs come from `user.tenants`. |
+
+## Entitlements
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `loadEntitlements` | `forceRefresh = false` | `Promise<boolean>` | Loads entitlements into the SDK cache. Call after authentication, and again with `forceRefresh` to refetch. Resolves `true` when loaded. |
+| `getFeatureEntitlement` | `key: string` | `Promise<Entitlement>` | Entitlement for a feature-flag key, read from the cache. |
+| `getPermissionEntitlement` | `key: string` | `Promise<Entitlement>` | Entitlement for a permission key, read from the cache. |
+
+Both getters read the on-device cache, so call `loadEntitlements` first.
+
+## Admin portal
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `openAdminPortal` | None | `Promise<void>` | Opens the Frontegg admin portal. |
+
+## Configuration
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getConstants` | `FronteggConstants` | The configuration the native SDK started with. |
+
+## Types
+
+### `Entitlement`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isEntitled` | `boolean` | Whether the user is entitled. |
+| `justification` | `string \| null` | Why not, when `isEntitled` is false — for example `NOT_AUTHENTICATED`, `ENTITLEMENTS_NOT_LOADED`, `MISSING_FEATURE`, `MISSING_PERMISSION`. |
+
+### `FronteggConstants`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `baseUrl` | `string` | Your Frontegg domain. |
+| `clientId` | `string` | Your Frontegg client ID. |
+| `applicationId` | `string \| null` | Application ID, when configured. |
+| `bundleId` | `string \| null` | The host app's bundle or package identifier. |
+| `useAssetLinks` | `boolean \| null` | iOS only — the `useAssetLinks` key from `Frontegg.plist`. |
+| `useAssetsLinks` | `boolean` | Android only — `FRONTEGG_USE_ASSETS_LINKS` from BuildConfig. |
+| `useChromeCustomTabs` | `boolean` | Android only — `FRONTEGG_USE_CHROME_CUSTOM_TABS` from BuildConfig. |
+
+### `FronteggLoginError`
+
+`login()` rejects with this. It extends `Error`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `FronteggLoginErrorCode` | Stable, cross-platform failure code. |
+| `message` | `string` | Human-readable message. |
+| `userCancelled` | `boolean` | Equivalent to `code === 'user_cancelled'`. |
+| `nativeCode` | `string?` | Raw platform code, preserved for debugging. |
+| `nativeMessage` | `string?` | Raw platform message. |
+
+### `FronteggLoginErrorCode`
+
+| Value | Meaning |
+|-------|---------|
+| `user_cancelled` | The user dismissed the login flow. |
+| `oauth_failed` | The OAuth exchange failed — bad code exchange, invalid state, failed authentication. |
+| `network` | The native SDK detected a network-level failure. |
+| `unknown` | Not classifiable; inspect `nativeCode` and `nativeMessage`. |
+
+The mapping is deliberately conservative: only failures the native layer can positively identify
+get a specific code. Everything else is `unknown`, with the raw platform detail preserved.
+
+```tsx
+import { login, type FronteggLoginError } from '@frontegg/react-native';
+
+try {
+  await login();
+} catch (e) {
+  const error = e as FronteggLoginError;
+  if (!error.userCancelled) {
+    console.warn(error.code, error.nativeCode);
+  }
+}
+```
+
+### `User`
+
+`IUserProfile` from `@frontegg/rest-api`, plus:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tenants` | `ITenantsResponse[]` | Every tenant the user belongs to. |
+| `activeTenant` | `ITenantsResponse` | The currently active tenant. |