client.setupAuth()

Present the auth frame and drive the customer through email/OTP authentication.

client.setupAuth() is the lighter-weight counterpart to client.connect() for headless and Customer API integrations. It drives the customer through email/OTP authentication only, without the full connect UI, then delivers encrypted credentials on completion.

The provider presents the auth frame in a full-screen modal. For an inline alternative, render <MoonPayAuth> instead.

Precondition: a clientToken must be present in the client context before calling this method. The token is populated automatically when client.getConnection() resolves with status: "connectionRequired". If no token is present, setupAuth() resolves immediately with err({ kind: "configurationError", ... }) without mounting a frame.

AuthFlow.tsx

import { useMoonPay, type AuthEvent } from "@moonpay/platform-sdk-react-native";

export function AuthFlow() {
  const { client } = useMoonPay();

  const startAuth = async () => {
    // Ensure the client context has a clientToken first.
    const connectionResult = await client.getConnection();
    if (!connectionResult.ok) {
      console.error(connectionResult.error.message);
      return;
    }
    if (connectionResult.value.status !== "connectionRequired") {
      // Already connected — no auth step needed.
      return;
    }

    const authResult = await client.setupAuth({
      onEvent: (event: AuthEvent) => {
        switch (event.kind) {
          case "ready":
            break;
          case "complete":
            // Emitted only for active or termsAcceptanceRequired connections.
            // Credentials are already applied to the client.
            console.log(event.payload.status);
            break;
          case "error":
            console.error(event.payload.code, event.payload.message);
            break;
        }
      },
    });

    if (!authResult.ok) {
      console.error(authResult.error.kind, authResult.error.message);
      return;
    }

    const authFrame = authResult.value;

    // You can dispose the frame at any time:
    // authFrame.dispose();
  };

  // ...
}

---

Parameters

Property	Type	Required	Description
onEvent	(event: AuthEvent) => void		Callback invoked for auth flow events. See AuthEvent.

AuthEvent

onEvent receives events as the auth flow progresses. Use event.kind to decide how to handle each event.

kind	Payload	When you receive it
"ready"	—	The auth UI is rendered and ready to be shown.
"complete"	Connection	Emitted only when the connection is active or termsAcceptanceRequired. Credentials are already applied.
"error"	ConnectionError	The flow encountered an error.

ConnectionError is discriminated by code:

code	Extra fields	Description
"validationError"	errors: ConfigValidationFieldError[]	One or more session/client/public-key fields are invalid.
"generic"	message?: string	A generic connection failure.

ConfigValidationFieldError entries have code: "invalidSessionToken" | "invalidClientToken" | "invalidPublicKey" and a developer-facing message.

Result

client.setupAuth() returns a Result<AuthFrame, SetupAuthError>.

Result envelope

Result<AuthFrame, SetupAuthError>

Field	Type	Required	Description
ok	boolean	✅	Whether the operation succeeded.
value	AuthFrame		Present when ok is true.
error	SetupAuthError		Present when ok is false.

AuthFrame

Field	Type	Required	Description
dispose	() => void	✅	Unmounts the frame and detaches event listeners.

SetupAuthError

SetupAuthError covers failures to mount the frame, a missing clientToken, customer dismissal, and in-frame errors. Per-flow errors inside the frame surface with full details through the "error" event; the method then resolves with a generic SetupAuthError.

Field	Type	Required	Description
kind	"configurationError" | "genericError"	✅	The error category.
message	string	✅	Developer-friendly details.

"configurationError" is returned when no clientToken is present in the client context. "genericError" is returned when the customer dismisses the modal (message: "Auth flow dismissed"), when the frame emits an "error" event, or when the frame fails to load.

types.ts

type AuthFrame = {
  dispose: () => void;
};

type SetupAuthError = {
  kind: "configurationError" | "genericError";
  message: string;
};