Add authentication in 5 minutes
Quickstart — browser SDK (publishable key) and server SDK (secret key).
Auth uses two separate SDKs, one per execution context.
| Package | Key | Context | |
|---|---|---|---|
| Browser | @mailmus/auth | Publishable | Sign-up and sign-in for your Customers, running in their browser |
| Server | mailmus | Secret | Administration (listing or banning users, Organizations, and so on), never on the client |
React app? Use @mailmus/auth-react
It is the fastest path: ready-made components (<SignIn>, <SignUp>, <UserButton>, MFA enrollment, and more) built on @mailmus/auth, with no form to write yourself.
npm install @mailmus/auth-reactimport { MailmusAuthProvider, SignIn, SignedIn, SignedOut, UserButton } from "@mailmus/auth-react";
import "@mailmus/auth-react/styles.css";
<MailmusAuthProvider publishableKey="mailmus_publishable_key_live_...">
<UserButton />
<SignedOut>
<SignIn redirectUri={window.location.origin + "/"} />
</SignedOut>
<SignedIn>{/* ... */}</SignedIn>
</MailmusAuthProvider>See the React reference for the details. For full control over the UI (another framework, an existing design system), use the raw browser SDK below — it is what @mailmus/auth-react uses internally.
React Native app?
npx expo install @mailmus/auth-react-native expo-secure-store expo-web-browserIt brings secure storage (Keychain/Keystore) and OAuth through the system browser (no webview) — see the React Native reference.
Browser SDK — sign-up and sign-in
npm install @mailmus/authMailmusAuthClient holds state (session, refresh in flight) — create it once, in a dedicated file:
// lib/mailmus-auth.ts
import { MailmusAuthClient } from "@mailmus/auth";
export const auth = new MailmusAuthClient({ publishableKey: "mailmus_publishable_key_live_..." });That is all: the project is decoded straight from the key, and serverURL/hostedPagesURL point at production by default (set them only for local or staging).
import { isMfaChallenge } from "@mailmus/auth";
import { auth } from "./lib/mailmus-auth";
const result = await auth.signIn({ email: "user@example.com", password: "hunter2" });
if (isMfaChallenge(result)) {
// The user has two-factor authentication on (TOTP).
const { customer } = await auth.mfa.verify({ challengeToken: result.challengeToken, code: "123456" });
} else {
console.log(result.customer);
}auth.session.getState() returns the current session state (signed-out / signed-in), and auth.session.subscribe(listener) lets you react to changes — useful to drive your UI (a React hook, for instance).
OAuth (Google, GitHub, Apple)
await auth.oauth.redirect({
provider: "google",
redirectUri: "https://yourapp.com/callback",
});The SDK never talks to Google, GitHub or Apple directly — everything goes through the Mailmus hosted pages. redirectUri must appear in your project's redirect allowlist (Project → Auth Settings).
Phone (SMS)
await auth.requestPhoneOtp({ phone: "+33612345678" });
const result = await auth.verifyPhoneOtp({ phone: "+33612345678", code: "123456" });Same idea as email: Mailmus generates the code, sends the SMS and verifies it — no SMS provider account to create on your side. Available on the Auth Pro tier. Details in the Phone guide.
Server SDK — administration
npm install mailmusimport { SDK } from "mailmus";
const mailmus = new SDK({ bearer: process.env.MAILMUS_SECRET_KEY });
const { data } = await mailmus.customers.customerAdminList({ projectId: "proj_xxx" });Next
- OAuth, Phone, MFA, Organizations, Sessions — detailed guides, feature by feature.
- API Reference — every admin endpoint.
- Browser SDK reference — the complete list of
@mailmus/authmethods.