-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.
+
Frontegg React Native SDK
-## ๐ฆ Peer Dependencies
+
+ Authentication and user management for your React Native app โ one package, both platforms.
+
-Install the required peer dependencies in your app:
+
+
+
+
+
+
+
+
+---
+
+[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 (
+
+
+ {/* your navigator */}
+
+
+ );
+}
+```
-- 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 (
+
+ {isAuthenticated ? : }
+
+ );
+}
+```
-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
new file mode 100644
index 0000000..4844d31
--- /dev/null
+++ 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` | Opens the login flow. `loginHint` pre-fills the identifier field. Resolves when login completes; rejects with a `FronteggLoginError`. |
+| `logout` | None | `Promise` | Signs the user out and clears stored credentials. |
+| `loginWithPasskeys` | None | `Promise` | Signs in with a passkey. Needs iOS 15+ or Android API 26+. |
+| `registerPasskeys` | None | `Promise` | Registers a passkey for the signed-in user. |
+| `refreshToken` | None | `Promise` | Forces a token refresh. The SDK also refreshes on its own in the background. |
+| `requestAuthorize` | `refreshToken: string` `deviceTokenCookie?: string` | `Promise` | Establishes a session from an existing refresh token, without opening the login flow. |
+
+### Social and direct login
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `directLoginAction` | `type: string` `data: string` `ephemeralSession = true` `additionalQueryParams?: Record` | `Promise` | 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` | Whether the session is currently stepped up. Omit `maxAge` for no age limit. |
+| `stepUp` | `maxAge?: number` (seconds) | `Promise` | Starts step-up authentication (MFA or re-auth). |
+
+## Tenants
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `switchTenant` | `tenantId: string` | `Promise` | Switches the active tenant. IDs come from `user.tenants`. |
+
+## Entitlements
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `loadEntitlements` | `forceRefresh = false` | `Promise` | Loads entitlements into the SDK cache. Call after authentication, and again with `forceRefresh` to refetch. Resolves `true` when loaded. |
+| `getFeatureEntitlement` | `key: string` | `Promise` | Entitlement for a feature-flag key, read from the cache. |
+| `getPermissionEntitlement` | `key: string` | `Promise` | 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` | 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. |
+
