React Native SDK

The @auth-gate/react-native SDK brings AuthGate authentication to React Native and Expo apps. OAuth flows open the system browser and return via deep link, tokens are stored in secure storage, and session restore happens automatically on app launch.

Installation

npm install @auth-gate/react-native

Install the required Expo modules:

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

Deep link setup

The SDK uses deep links to receive OAuth callbacks. Configure your app's URL scheme:

Expo (managed)

Add to your app.json:

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

Bare React Native

Follow the React Native deep linking guide to register your custom URL scheme for both iOS and Android.

Then register the callback URL in the AuthGate dashboard:

myapp://auth/callback

Navigate to Dashboard → Callback URLs and add the URL above.

Setup

1. Wrap your app with AuthProvider

App.tsx

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>
  );
}

2. Use the hooks

screens/Profile.tsx

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

OAuth

Opens the system browser for the OAuth flow. The user authenticates with the provider, and the SDK handles the deep link callback automatically.

const { login } = useAuth();

await login.withOAuth("google");
await login.withOAuth("github");
await login.withOAuth("discord");
await login.withOAuth("azure");
await login.withOAuth("apple");

Email

const { login } = useAuth();

// Sign up (with optional locale)
await login.signUp("alice@example.com", "password123", "Alice", { locale: "it" });

// Sign in (with optional locale)
const result = await login.withEmail("alice@example.com", "password123", { locale: "it" });

if (result?.mfaRequired) {
  // MFA challenge — prompt user for code
  await login.verifyMfa(result.challenge, totpCode, "totp");
}

Magic link

await login.withMagicLink("alice@example.com");
// User receives an email with a link that opens the app via deep link

SMS

// Send verification code
await login.withSms("+15551234567");

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

MFA

After an email sign-in returns an MFA challenge:

await login.verifyMfa(challenge, code, "totp");        // TOTP authenticator
await login.verifyMfa(challenge, code, "sms");         // SMS code
await login.verifyMfa(challenge, code, "backup_code"); // Backup code

Route protection

Use AuthGuard to conditionally render screens based on auth state:

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

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

Configuration

Name
apiKey
Type
string
Description
Your AuthGate API key.
Name
baseUrl
Type
string
Description
URL of your AuthGate instance.
Name
scheme
Type
string
Description
Deep link scheme for OAuth callbacks (e.g. "myapp").
Name
sessionMaxAge
Type
number
Description
Session lifetime in seconds (default: 7 days).
Name
callbackPath
Type
string
Description
Deep link callback path fragment.

API reference

`useAuth()`

Returns the full auth context.

Property	Type	Description
`user`	`AuthGateUser \| null`	Current user or null
`loading`	`boolean`	True while restoring session on launch
`login`	`LoginMethods`	All login methods (see below)
`logout`	`() => Promise<void>`	Sign out and clear secure storage
`refresh`	`() => Promise<void>`	Re-verify the stored token

`LoginMethods`

Method	Description
`withOAuth(provider)`	Start OAuth flow in system browser
`withEmail(email, password, options?)`	Email sign-in (may return MFA challenge). Options: `{ locale?: string }`
`signUp(email, password, name?, options?)`	Email registration. Options: `{ locale?: string }`
`withMagicLink(email, options?)`	Send a magic link. Options: `{ locale?: string }`
`withSms(phone)`	Send SMS verification code
`verifySmsCode(phone, code)`	Verify SMS code
`verifyMfa(challenge, code, method)`	Complete MFA challenge

`useSession()`

Shorthand that returns just the user:

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

How sessions work

Tokens are stored in Expo Secure Store (Keychain on iOS, EncryptedSharedPreferences on Android)
On app launch, the stored token is verified server-side
If the token is expired, the refresh token is used automatically
Token refresh is scheduled before expiry to maintain seamless sessions