React Native
The @mailmus/auth-react-native SDK — secure storage (Keychain/Keystore) and OAuth through the system browser, no webview.
Package: @mailmus/auth-react-native (source) — a thin layer on top of the browser SDK, which already handles everything that is not platform-specific (HTTP, session refresh, MFA, sessions). This package replaces only two things: token storage (Keychain/Keystore instead of localStorage) and the OAuth flow (the system browser instead of window.open).
[!IMPORTANT] This package is still under development; the API may change before 1.0.
Installation
npx expo install @mailmus/auth-react-native expo-secure-store expo-web-browserIt works in managed Expo and in bare React Native with the Expo modules installed (npx install-expo-modules, officially supported since Expo SDK 44) — it is not a managed-Expo-only package, despite the dependency.
Expo Go or a development build?
createMailmusAuthClient() (sign-up/in, MFA, sessions, secure storage) works in Expo Go — expo-secure-store needs no native code beyond what the Expo Go app already ships. startOAuth(), on the other hand, does not work in Expo Go: it needs a deep link with a custom URI scheme (myapp://oauth-callback), and an app running inside Expo Go uses Expo Go's scheme, not its own. That is a platform limit, not something this SDK can work around — Expo's own documentation is explicit: "Expo Go cannot be used for local development and testing of OAuth or OpenID Connect-enabled apps due to the inability to customize your app scheme." Use a development build (expo-dev-client, npx expo run:ios/run:android, or an EAS Build dev profile) to test OAuth.
Usage
Since createMailmusAuthClient() holds state (session, refresh in flight), call it once at app startup (in your root component, before the first render, for instance) rather than on demand inside a screen:
// lib/mailmus-auth.ts
import { createMailmusAuthClient } from "@mailmus/auth-react-native";
export const authPromise = createMailmusAuthClient({ publishableKey: "mailmus_publishable_key_live_..." });publishableKey alone is enough in production — the project is decoded straight from the key, and serverURL/hostedPagesURL point at production by default.
// any other file
import { authPromise } from "./lib/mailmus-auth";
const client = await authPromise;
// The same MailmusAuthClient API as the browser SDK from here on.
const result = await client.signIn({ email, password });createMailmusAuthClient() is asynchronous because reading the Keychain/Keystore is inherently asynchronous (unlike localStorage in a browser) — the client it returns is already fully hydrated (client.session.getState() resolves straight to signed-in/signed-out, never loading).
React context (recommended)
<MailmusAuthProvider> wraps the promise above in the same context and hooks as @mailmus/auth-react on the web:
import { MailmusAuthProvider, useAuth } from "@mailmus/auth-react-native";
export default function App() {
return (
<MailmusAuthProvider publishableKey="mailmus_publishable_key_live_...">
<RootScreen />
</MailmusAuthProvider>
);
}
function RootScreen() {
const { isLoaded, isSignedIn, customer } = useAuth();
if (!isLoaded) return <SplashScreen />; // the SecureStore read is still in flight
return isSignedIn ? <Text>Hello, {customer?.email}</Text> : <SignInScreen />;
}Unlike the web <MailmusAuthProvider> (synchronous, localStorage), useAuth().isLoaded starts at false — there is a real SecureStore read happening before the client even exists, not only before its session is known.
OAuth — system browser, no webview
[!IMPORTANT] Requires a development build, not Expo Go.
// projectId, publishableKey and hostedPagesURL are read straight off `client`.
await startOAuth({
client,
provider: "google",
redirectUri: "myapp://oauth-callback", // must appear in the project allowlist
});It opens a real ASWebAuthenticationSession (iOS) / Custom Tabs (Android) session through expo-web-browser, and finishes through a deep link back into your app — not an embedded webview. Setup:
- Turn the provider (Google, GitHub, Apple) on under Project → Authentication — as in the browser, there is no OAuth app to create yourself; Mailmus hosts a shared client per provider.
- Add your deep link (a custom URI scheme,
myapp://oauth-callbackfor instance) to the Allowed redirect URLs.
No server change was needed for this flow: the hosted OAuth bridge already switches to a full redirect (rather than a postMessage) whenever it is not opened through window.open — which is exactly what a system browser session is.
Magic link and forgotten password — a real limit
client.requestMagicLink() and client.forgotPassword() work normally (pure API calls, no platform dependency). The limit is on the receiving side: for the emailed link to reopen your app rather than an ordinary browser tab, your app has to set up Universal Links (iOS) / App Links (Android) on your own domain (apple-app-site-association, assetlinks.json) — configuration specific to each client app, which this SDK cannot do for you. A custom URI scheme is not reliable for a link sent by email, depending on the mail client, unlike the OAuth flow above, which your own code opens directly.
The one-time code (requestOtp/verifyOtp) does not have that limit — no link to click, the user types the code.
MFA and sessions
Identical to the browser SDK — pure API calls, no platform dependency:
const { secret, otpauthUrl } = await client.mfa.enroll();
const { backupCodes } = await client.mfa.confirm({ code });
await client.sessions.list();Rendering a QR code for otpauthUrl, or any other UI, is out of scope for this SDK (a library, not components) — use something like react-native-qrcode-svg.
Out of scope (on the roadmap)
Pre-built RN components — a separate piece of work if needed, on the same phasing as @mailmus/auth-react on the web.
Next
- OAuth, MFA — the detailed behaviour is identical to the browser SDK.
- Browser SDK — the complete underlying API.