Mailmus
Auth

OAuth (Google, GitHub, Apple)

Social sign-in without configuring a single OAuth app — Mailmus hosts the credentials for you.

Zero configuration on the provider side

You have no OAuth app to create at Google, GitHub or Apple. Mailmus hosts a shared OAuth client for each provider, and the SDK never talks to Google, GitHub or Apple directly — everything goes through the Mailmus hosted pages ({hostedPagesURL}/auth/{projectId}/oauth/{provider}), which exchange the code and return Mailmus tokens to your app.

So there is no clientId or clientSecret to fill in anywhere, in your code or in your dashboard: only a provider to turn on.

Turn a provider on

Project → Authentication → Sign-in methods, click "Sign in with Google" (or GitHub, or Apple). Every provider you turn on shows up automatically as a button in <SignIn>/<SignUp> if you use @mailmus/auth-react, or through auth.getHostedConfig() if you build your own UI with the raw SDK.

Redirect allowlist

redirectUri — the page of your app the user comes back to after the provider — must appear in Project → Authentication → Allowed redirect URLs. Any URL absent from that list is refused by the server, before it even reaches Google, GitHub or Apple.

Apple: the address can be hidden

When authorizing, an end-user signing in with Apple can choose "Hide My Email". Apple then creates a unique relay address, of the form wyyn29v87v@privaterelay.appleid.com, and that is the one you receive. Your emails are forwarded from it to their real inbox, but their real address is never shared with you.

Two consequences to plan for in your product.

The same human can exist twice. If they first sign in with Apple while hiding their address, then sign up later with their real address, you end up with two distinct Customers. Nothing lets you match them: the relay address is opaque by design, which is the whole point. That is how Sign in with Apple works, not a Mailmus quirk. If your product absolutely has to merge those two accounts, plan an explicit step in your app, for example by having the end-user confirm a code sent to each of the two addresses.

The relay address can stop working. The end-user can withdraw your app's access at any time from their Apple account settings. Your sends to that address then start bouncing. Treat that bounce as a deliberate departure rather than a technical error: the person chose to cut the link.

With @mailmus/auth-react

The OAuth buttons are built into <SignIn>/<SignUp> as soon as redirectUri is provided:

<SignIn redirectUri="https://yourapp.com/" oauthMode="popup" />

oauthMode is either "redirect" (full-page navigation, the default) or "popup" (a pop-up window, which resolves directly with the tokens without leaving the page — the component listens for the message for you).

With the raw SDK

// Full-page redirect — never resolves, it navigates the current page.
await auth.oauth.redirect({ provider: "google", redirectUri });

// Popup — resolves with the tokens as soon as the provider is done.
const tokens = await auth.oauth.popup({ provider: "google", redirectUri });

In redirect mode, call auth.oauth.handleRedirectCallback() when your redirectUri page loads, to consume the tokens returned in the URL fragment (#access_token=...):

// On the callback page
const tokens = auth.oauth.handleRedirectCallback();
if (tokens) {
  // Signed in — the SDK has already updated auth.session.getState().
}

MFA and OAuth

If the user has two-factor authentication on, an OAuth sign-in can return an MFA challenge instead of tokens — <SignIn> handles that case for you. With the raw SDK, auth.oauth.popup() and handleRedirectCallback() return the tokens directly (MFA having already been validated upstream on the hosted pages); see MFA for the details of the flow.

Next

  • MFA — two-factor authentication, verification and enrollment.
  • API Reference — the oauth/* endpoints.

On this page