Skip to main content
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 Identity 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

FieldTypeRequiredDescription
containerHTMLElement✅A DOM element to render the Auth frame into.
onEvent(event: AuthEvent) => voidCallback 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.
kindPayloadWhen you receive it
"ready"—The auth UI is rendered and ready to be shown.
"complete"ConnectionThe customer authenticated. status is "active", or "termsAcceptanceRequired" when a Terms of Use attestation is still outstanding.
"error"AuthEventErrorThe flow encountered an error.

​
AuthEventError

The error event payload comes from the underlying auth frame. It is discriminated by code.
FieldTypeRequiredDescription
code"validationError" | "generic"✅The error category.
errors{ code: string; message: string }[]Field-level errors. Present when code is "validationError".
messagestringDeveloper-friendly details. May be present when code is "generic".

​
Result

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

​
Result envelope

Result<AuthFrame, SetupAuthError>
FieldTypeRequiredDescription
okboolean✅Whether the operation succeeded.
valueAuthFramePresent when ok is true.
errorSetupAuthErrorPresent when ok is false.

​
AuthFrame

FieldTypeRequiredDescription
dispose() => void✅Unmounts the frame. After you call this, no further events are dispatched to your onEvent callback.

​
SetupAuthError

FieldTypeRequiredDescription
kind"configurationError" | "genericError"✅The error category. "configurationError" means the client has no token from a prior connection check.
messagestring✅Developer-friendly details.
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;
};