@auth-gate/react-native

React Native / Expo SDK for AuthGate — drop-in authentication with OAuth, email, SMS, and MFA for mobile apps.

Installation

npm install @auth-gate/react-native

Peer dependencies: react >= 18, react-native >= 0.72, expo-secure-store, expo-web-browser, expo-linking

npx expo install expo-secure-store expo-web-browser expo-linking

Quick Start

1. Configure Deep Links

Add your custom URL scheme to app.json:

{
  "expo": {
    "scheme": "myapp"
  }
}

Register the callback URL myapp://auth/callback in the Callbacks tab of your AuthGate dashboard.

2. Wrap Your App

import { AuthProvider } from "@auth-gate/react-native";

export default function App() {
  return (
    <AuthProvider
      config={{
        apiKey: "ag_...",
        baseUrl: "https://www.authgate.dev",
        scheme: "myapp",
      }}
    >
      <Navigation />
    </AuthProvider>
  );
}

3. Use the Hooks

import { useAuth } from "@auth-gate/react-native";

function ProfileScreen() {
  const { user, loading, login, logout } = useAuth();

  if (loading) return <ActivityIndicator />;
  if (!user) return <LoginScreen />;

  return (
    <View>
      <Text>Hello, {user.name}</Text>
      <Button title="Sign out" onPress={logout} />
    </View>
  );
}

Authentication Methods

OAuth

Opens the system browser for the OAuth flow and returns via deep link.

const { login } = useAuth();

// Google, GitHub, Discord, Azure (Microsoft), Apple
await login.withOAuth("google");

Email

const { login } = useAuth();

// Sign up
await login.signUp("[email protected]", "password123", "Alice");

// Sign in
const result = await login.withEmail("[email protected]", "password123");

if (result?.mfaRequired) {
  // Handle MFA challenge
  await login.verifyMfa(result.challenge, totpCode, "totp");
}

Magic Link

await login.withMagicLink("[email protected]");
// User receives a link that opens the app via deep link

SMS

await login.withSms("+15551234567");
await login.verifySmsCode("+15551234567", "123456");

MFA

// After email sign-in returns mfaRequired
await login.verifyMfa(challenge, code, "totp");   // TOTP
await login.verifyMfa(challenge, code, "sms");    // SMS
await login.verifyMfa(challenge, code, "backup_code"); // Backup code

Route Protection

import { AuthGuard } from "@auth-gate/react-native";

function App() {
  return (
    <AuthProvider config={config}>
      <AuthGuard
        redirectTo="Login" // navigation route name
        loadingFallback={<ActivityIndicator />}
      >
        <ProtectedScreens />
      </AuthGuard>
    </AuthProvider>
  );
}

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your AuthGate API key | | baseUrl | string | Yes | AuthGate instance URL | | scheme | string | Yes | Deep link scheme (e.g. "myapp") | | sessionMaxAge | number | No | Session TTL in seconds (default: 604800 / 7 days) | | callbackPath | string | No | Deep link callback path (default: "auth/callback") |

Hooks

useAuth()

const { user, loading, login, logout, refresh } = useAuth();

| Property | Type | Description | |----------|------|-------------| | user | AuthGateUser \| null | Current user or null | | loading | boolean | True while restoring session | | login | LoginMethods | OAuth, email, SMS, magic link, and MFA methods | | logout | () => Promise<void> | Sign out and clear secure storage | | refresh | () => Promise<void> | Re-verify the stored token |

useSession()

const user = useSession(); // AuthGateUser | null

How It Works

• Tokens are stored in Expo Secure Store (Keychain on iOS, EncryptedSharedPreferences on Android)
• OAuth flows open the system browser via expo-web-browser and return via deep link
• Session is automatically restored on app launch by verifying the stored token
• Token refresh is scheduled automatically before expiry

Types

import type {
  AuthGateUser,
  AuthGateNativeConfig,
  AuthContextValue,
  LoginMethods,
  MfaChallengeResult,
  OAuthProvider,
} from "@auth-gate/react-native";

License

MIT