client.setupAuth()

Render the Auth frame to authenticate a customer with email and OTP.

Render the Auth frame into your UI to authenticate the customer with email and a one-time passcode. The Auth frame is the lighter-weight counterpart to client.connect() for headless and Customer API integrations. It handles authentication only, with no payment-method setup or KYC steps. When the customer finishes, the SDK decrypts the returned credentials and primes the client so that subsequent SDK calls are authenticated automatically.

Call client.getConnection() first. The connection check primes the client with the token the Auth frame needs. If you call setupAuth() without a prior connection check that resolved with status: "connectionRequired", it returns a configurationError.

Setup auth

import { createClient, type AuthEvent } from "@moonpay/platform-sdk-web";

const client = createClient({ sessionToken: "c3N0XzAwMQ==" });

const connectionResult = await client.getConnection({ skipKyc: true });

if (!connectionResult.ok) {
  // Handle error
  return;
}

if (connectionResult.value.status === "connectionRequired") {
  const authResult = await client.setupAuth({
    container: document.querySelector("#authContainer"),
    onEvent: (event: AuthEvent) => {
      switch (event.kind) {
        case "ready":
          // The auth UI is rendered. Reveal the container if you hide it while loading.
          break;
        case "complete":
          if (event.payload.status === "active") {
            // Customer authenticated — SDK calls are now authenticated.
            console.log(event.payload.customer.id);
          }
          break;
        case "error":
          console.error(event.payload);
          break;
      }
    },
  });

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

  // Remove the frame from the DOM now that the flow has completed:
  authResult.value.dispose();
}

The promise returned by client.setupAuth() resolves after the customer completes the auth flow (or an error ends it). Track flow progress — including the moment the UI is ready to show — through onEvent, not by awaiting the promise.

---

Parameters

Field	Type	Required	Description
container	HTMLElement	✅	A DOM element to render the Auth frame into.
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	The customer authenticated. status is "active", or "termsAcceptanceRequired" when a Terms of Use attestation is still outstanding.
"error"	AuthEventError	The flow encountered an error.

AuthEventError

The error event payload comes from the underlying auth frame. It is discriminated by code.

Field	Type	Required	Description
code	"validationError" | "generic"	✅	The error category.
errors	{ code: string; message: string }[]		Field-level errors. Present when code is "validationError".
message	string		Developer-friendly details. May be present when code is "generic".

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. After you call this, no further events are dispatched to your onEvent callback.

SetupAuthError

Field	Type	Required	Description
kind	"configurationError" | "genericError"	✅	The error category. "configurationError" means the client has no token from a prior connection check.
message	string	✅	Developer-friendly details.

TS Definitions

types.ts

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

type AuthEvent =
  | { kind: "ready" }
  | {
      kind: "complete";
      /** status is "active" or "termsAcceptanceRequired" */
      payload: Connection;
    }
  | { kind: "error"; payload: AuthEventError };

type AuthEventError =
  | {
      code: "validationError";
      errors: { code: string; message: string }[];
    }
  | {
      code: "generic";
      message?: string;
    };

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