Skip to Content
DocumentationAPI ReferenceModal API

Modal API

⚡ 8 min read

The Transcodes SDK provides three modal methods for authentication. All modals return Promises with standardized ApiResponse objects.

Overview

ModalPurposeWhen to Use
openAuthLoginModal()Login & SignupInitial user authentication
openAuthModal()Account ManagementProfile/Passkey/MFA settings
openAuthMfaModal()Multi-Factor AuthSensitive operations (2FA)

About projectId parameter: In almost all cases, the projectId is automatically provided from the SDK initialization configuration. If you explicitly provide it in the modal method parameters, it will override the automatically provided value.

Methods

openAuthLoginModal()

Opens the integrated login and signup modal. New users create accounts via email verification, while existing users sign in with Passkey or Email OTP.

transcodes.openAuthLoginModal(params: {
  projectId?: string;
  userId?: string;
}): Promise<ApiResponse<AuthResult[]>>

Parameters:

ParameterTypeRequiredDescription
projectIdstringNoProject ID (automatically provided in most cases)
userIdstringNoUser ID (returning users)

Returns: Promise<ApiResponse<AuthResult[]>>

Note: The projectId parameter is automatically provided in almost all cases from the SDK initialization configuration. If you explicitly provide it, it will override the automatically provided value.

When to use: Login button clicks, protected page access, unauthenticated state detection

User Flow:

  • New users: Email → Terms acceptance → OTP verification → Optional Passkey setup
  • Returning users: Email → Authentication method (Passkey/Email OTP) → Complete
  • Passkey management: Test, edit, delete, or add Passkeys after login

Example:

const result = await transcodes.openAuthLoginModal({
  projectId: '{YOUR_PROJECT_ID}',
});
 
if (result.success) {
  const { user } = result.payload[0];
  console.log('Logged in:', user.email);
  // Token is automatically stored and managed by the SDK
  // Access it later with: await transcodes.token.getAccessToken()
}

openAuthModal()

Opens the account management console. Authenticated users can manage their profile, Passkeys, and MFA settings.

transcodes.openAuthModal(params: {
  userId: string;
  projectId?: string;
}): Promise<ApiResponse<null>>

Parameters:

ParameterTypeRequiredDescription
userIdstringYesUser ID
projectIdstringNoProject ID (automatically provided in most cases)

Returns: Promise<ApiResponse<null>>

Note: The projectId parameter is automatically provided in almost all cases from the SDK initialization configuration. If you explicitly provide it, it will override the automatically provided value.

Requires authenticated user. userId is mandatory.

Management Options:

  • Profile: Name and email (email changes require OTP verification)
  • Passkeys: View, test, rename, delete, and add registered Passkeys
  • MFA: Manage external security devices (YubiKey, FIDO2) and TOTP apps (Google Authenticator, Authy)

When to use: Settings menu, post-signup Passkey/MFA setup prompts

Example:

const user = await transcodes.token.getCurrentUser();
 
if (user) {
  await transcodes.openAuthModal({
    projectId: '{YOUR_PROJECT_ID}',
    userId: user.id,
  });
  // Modal closes when user finishes managing their account
  // No return value - settings are updated on the server
}

openAuthMfaModal()

Requires multi-factor authentication (MFA/2FA) before performing sensitive operations. Even after login, critical actions like account deletion, email changes, or high-value transactions require additional verification.

transcodes.openAuthMfaModal(params: {
  userId: string;
  projectId?: string;
}): Promise<ApiResponse<AuthResult[]>>

Parameters:

ParameterTypeRequiredDescription
userIdstringYesUser ID
projectIdstringNoProject ID (automatically provided in most cases)

Returns: Promise<ApiResponse<AuthResult[]>>

Note: The projectId parameter is automatically provided in almost all cases from the SDK initialization configuration. If you explicitly provide it, it will override the automatically provided value.

Re-authentication required for sensitive operations. userId is mandatory.

Available MFA Methods:

  • External security devices: YubiKey, FIDO2 devices (USB, NFC, Bluetooth)
  • TOTP apps: Google Authenticator, Authy, 1Password (6-digit rotating codes)
  • Email OTP: 6-digit code sent via email (backup method, always available)

Backup guarantee: Email OTP ensures account access even if USB key is lost or TOTP app is unavailable.

MFA-required operations: Account deletion, email changes, payment method updates, security setting modifications, admin panel access, high-value transactions

User Flow:

  1. App triggers openAuthMfaModal() when user attempts sensitive operation
  2. User selects MFA method (external device/TOTP app/Email OTP)
  3. On success, operation proceeds; on failure, retry or switch to Email OTP

Example:

const user = await transcodes.token.getCurrentUser();
 
if (user) {
  const mfaResult = await transcodes.openAuthMfaModal({
    projectId: '{YOUR_PROJECT_ID}',
    userId: user.id,
  });
 
  if (mfaResult.success) {
    const mfaToken = mfaResult.payload[0].token;
    console.log('MFA verification successful');
    // Use mfaToken to authorize sensitive operations on your backend
  } else {
    console.error('MFA verification failed:', mfaResult.error);
  }
}

Type Definitions

ApiResponse<T>

All modal methods return this standardized response:

interface ApiResponse<T> {
  success: boolean;
  payload: T;
  error?: string;
  message?: string;
}

AuthResult

interface AuthResult {
  token: string;
  user: User;
}

User

interface User {
  id?: string;
  projectId?: string;
  name?: string;
  email?: string;
  roles?: string;
  metadata?: Record<string, string | number | boolean | null | undefined>;
  createdAt?: Date | string;
  updatedAt?: Date | string;
}
Last updated on
Events APIOverview