React Native

Authenticate users in your Expo app in under 5 minutes

Crossmint Auth is designed for staging and moving fast. For production applications, Crossmint strongly recommends connecting your own authentication provider for full control over user management. See the Bring Your Own Auth guide.

Crossmint Auth on React Native is headless — there is no pre-built login modal. You build your own UI and call the SDK hooks directly. This guide walks through both email OTP and OAuth login flows.

Before you start

Set up your project and get an API key.

Expo Wallets Quickstart

See a full working example with auth and wallets.

1. Install the SDK

   Install the Crossmint React Native SDK and its required Expo peer dependencies:

   npm

   npm i @crossmint/client-sdk-react-native-ui expo-secure-store expo-web-browser expo-device
   

   yarn add @crossmint/client-sdk-react-native-ui expo-secure-store expo-web-browser expo-device
   

   pnpm add @crossmint/client-sdk-react-native-ui expo-secure-store expo-web-browser expo-device
   

   bun add @crossmint/client-sdk-react-native-ui expo-secure-store expo-web-browser expo-device
   

   The SDK requires the following Expo packages:

   Package	Purpose
   expo-secure-store	Encrypted token storage (Keychain on iOS, Keystore on Android)
   expo-web-browser	Opens the OAuth consent screen in a system browser
   expo-device	Detects device capabilities for secure storage availability
   expo-linking	Listens for OAuth deep-link redirects back to your app

2. Configure your app scheme

   OAuth redirects require a deep link scheme so the browser can return to your app after login.

   Add a scheme to your app.json (or app.config.ts):

   app.json

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

   Expo Go uses a different scheme at runtime (exp://127.0.0.1:8081). The SDK detects Expo Go automatically and adjusts the redirect URI, so OAuth works during development without extra configuration. For production builds, the scheme value above is used.

3. Add the Crossmint providers to your app

   Wrap your application with CrossmintProvider and CrossmintAuthProvider.

   providers.tsx

   import {
       CrossmintProvider,
       CrossmintAuthProvider,
   } from "@crossmint/client-sdk-react-native-ui";
   
   type ProvidersProps = {
       children: React.ReactNode;
   };
   
   export default function Providers({ children }: ProvidersProps) {
       return (
           <CrossmintProvider
               apiKey={process.env.EXPO_PUBLIC_CROSSMINT_API_KEY!}
           >
               <CrossmintAuthProvider>
                   {children}
               </CrossmintAuthProvider>
           </CrossmintProvider>
       );
   }
   

   CrossmintAuthProvider Props

   Prop	Type	Description
   appSchema	string | string[]	Override the deep link scheme. Defaults to the scheme in your Expo config.
   storageProvider	StorageProvider	Custom token storage implementation. Defaults to expo-secure-store.
   onLoginSuccess	(user) => void	Callback fired after a successful login.

4. Build the login screen

   Use the useCrossmintAuth hook to access auth functions. Unlike the React web SDK, there is no pre-built modal — you call loginWithOAuth and crossmintAuth.sendEmailOtp / crossmintAuth.confirmEmailOtp directly.

   Email OTP Login

   LoginScreen.tsx

   import React, { useState } from "react";
   import {
       View,
       Text,
       TextInput,
       TouchableOpacity,
       ActivityIndicator,
       Alert,
   } from "react-native";
   import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
   
   export default function LoginScreen() {
       const { crossmintAuth, createAuthSession, status } =
           useCrossmintAuth();
   
       const [email, setEmail] = useState("");
       const [emailId, setEmailId] = useState("");
       const [otp, setOtp] = useState("");
       const [otpSent, setOtpSent] = useState(false);
       const [isPending, setIsPending] = useState(false);
   
       const sendOtp = async () => {
           if (!email.trim()) {
               Alert.alert("Error", "Enter a valid email address");
               return;
           }
           setIsPending(true);
           try {
               const res =
                   await crossmintAuth?.sendEmailOtp(email);
               if (res == null) {
                   throw new Error("Auth client not ready");
               }
               setEmailId(res.emailId);
               setOtpSent(true);
           } catch (error) {
               const message =
                   error instanceof Error
                       ? error.message
                       : "Failed to send OTP.";
               Alert.alert("Error", message);
           } finally {
               setIsPending(false);
           }
       };
   
       const verifyOtp = async () => {
           if (!otp.trim()) {
               Alert.alert("Error", "Enter the OTP code");
               return;
           }
           setIsPending(true);
           try {
               const oneTimeSecret =
                   await crossmintAuth?.confirmEmailOtp(
                       email,
                       emailId,
                       otp
                   );
               if (oneTimeSecret == null) {
                   throw new Error("Auth client not ready");
               }
               await createAuthSession(oneTimeSecret);
           } catch (error) {
               const message =
                   error instanceof Error
                       ? error.message
                       : "Invalid OTP. Try again.";
               Alert.alert("Error", message);
           } finally {
               setIsPending(false);
           }
       };
   
       if (status === "initializing") {
           return (
               <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
                   <ActivityIndicator size="large" />
               </View>
           );
       }
   
       return (
           <View style={{ flex: 1, padding: 20, justifyContent: "center" }}>
               <TextInput
                   style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
                   placeholder="Enter your email"
                   value={email}
                   onChangeText={setEmail}
                   editable={!otpSent}
               />
   
               {!otpSent ? (
                   <TouchableOpacity
                       style={{ backgroundColor: "#05b959", padding: 15, alignItems: "center" }}
                       onPress={sendOtp}
                       disabled={isPending}
                   >
                       {isPending ? (
                           <ActivityIndicator color="#fff" size="small" />
                       ) : (
                           <Text style={{ color: "#fff" }}>Send OTP</Text>
                       )}
                   </TouchableOpacity>
               ) : (
                   <>
                       <TextInput
                           style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
                           placeholder="Enter OTP code"
                           value={otp}
                           onChangeText={setOtp}
                       />
                       <TouchableOpacity
                           style={{ backgroundColor: "#05b959", padding: 15, alignItems: "center" }}
                           onPress={verifyOtp}
                           disabled={isPending}
                       >
                           {isPending ? (
                               <ActivityIndicator color="#fff" size="small" />
                           ) : (
                               <Text style={{ color: "#fff" }}>Verify OTP</Text>
                           )}
                       </TouchableOpacity>
                   </>
               )}
           </View>
       );
   }
   

   OAuth Login (Google, Twitter)

   OAuthButton.tsx

   import React, { useEffect } from "react";
   import { TouchableOpacity, Text } from "react-native";
   import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
   import * as Linking from "expo-linking";
   
   export default function OAuthButton() {
       const { loginWithOAuth, createAuthSession } =
           useCrossmintAuth();
   
       const url = Linking.useURL();
   
       useEffect(() => {
           if (url != null) {
               createAuthSession(url);
           }
       }, [url, createAuthSession]);
   
       return (
           <TouchableOpacity
               style={{ backgroundColor: "#4285f4", padding: 15, alignItems: "center" }}
               onPress={() => loginWithOAuth("google")}
           >
               <Text style={{ color: "#fff" }}>
                   Sign in with Google
               </Text>
           </TouchableOpacity>
       );
   }
   

   How OAuth Works on Android vs iOS

   The SDK handles platform differences automatically:

   • iOS: Uses WebBrowser.openAuthSessionAsync, which opens an in-app authentication session (ASWebAuthenticationSession). The redirect URL is intercepted by the authentication session before it reaches your app’s URL routing, so Linking.useURL() remains null after the OAuth flow. There is no double invocation — createAuthSession is called only once by the SDK internally.
   • Android: Uses WebBrowser.openBrowserAsync, which opens the system browser. The OAuth provider redirects back to your app via the deep link scheme. You must listen for the incoming URL with Linking.useURL() and pass it to createAuthSession yourself, as shown in the example above.

   The Linking.useURL() + createAuthSession pattern works on both platforms, so a single code path is sufficient.

5. Add logout and display user info

   HomeScreen.tsx

   import React from "react";
   import { View, Text, TouchableOpacity } from "react-native";
   import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
   
   export default function HomeScreen() {
       const { user, jwt, logout, status } = useCrossmintAuth();
   
       return (
           <View style={{ flex: 1, padding: 20 }}>
               <View
                   style={{
                       flexDirection: "row",
                       justifyContent: "space-between",
                       marginBottom: 20,
                   }}
               >
                   <Text style={{ fontSize: 20 }}>Welcome!</Text>
                   <TouchableOpacity onPress={logout}>
                       <Text style={{ color: "red" }}>Logout</Text>
                   </TouchableOpacity>
               </View>
   
               <Text>Email: {user?.email}</Text>
               <Text>User ID: {user?.id}</Text>
               <Text>Status: {status}</Text>
               <Text>JWT: {jwt ? "Present" : "None"}</Text>
           </View>
       );
   }
   

Auth Status Values

The status field returned by useCrossmintAuth can be one of the following:

Status	Description
"initializing"	The SDK is loading stored tokens and checking session validity
"logged-out"	No active session. Show your login screen
"in-progress"	An OAuth or OTP flow is currently in progress
"logged-in"	The user is authenticated. user and jwt are available

Token Storage

By default, the SDK stores authentication tokens using expo-secure-store, which encrypts data at rest using the platform keychain (iOS) or keystore (Android). This means tokens persist across app restarts and are protected by the device’s hardware-backed security.

You can provide a custom storage implementation via the storageProvider prop on CrossmintAuthProvider if you need a different storage backend.

Differences from the React Web SDK

Feature	React (Web)	React Native
Login UI	Pre-built modal via login()	Headless — build your own UI
Auth hook	useAuth()	useCrossmintAuth()
OAuth flow	Popup / redirect in browser	System browser via expo-web-browser
OAuth callback	Handled automatically	Listen with Linking.useURL() + createAuthSession()
Token storage	Browser localStorage / cookies	expo-secure-store (encrypted)
Package	@crossmint/client-sdk-react-ui	@crossmint/client-sdk-react-native-ui
Deep link scheme	Not required	Required in app.json for OAuth
Email OTP	Handled by modal	Call sendEmailOtp / confirmEmailOtp manually

Moving to Production

Crossmint Auth is designed for staging and getting started quickly. For production applications, Crossmint strongly recommends migrating to your own authentication provider for full control over user management.

When you are ready to go to production, Crossmint recommends:

1. Set up your own auth provider (Auth0, Firebase, Supabase, Stytch, etc.) and follow the Bring Your Own Auth guide to integrate it with Crossmint via JWT.
2. Create a developer account on the production console.
3. Create a production client API key on the API Keys page with the API scopes users.create, users.read, wallets.read.
4. Configure JWT authentication for your auth provider in the Crossmint Console.

Next Steps

• Create Smart Wallets on sign up using the wallets React Native quickstart
• Bring Your Own Auth, recommended for production
• Read and update user information
• Use webhooks to get notified when a user signs up
• React Native SDK Reference for the full API documentation