JavaScript SDK Reference

import { Magic } from 'magic-sdk';

let magic;

// Construct with an API key:
magic = new Magic('PUBLISHABLE_API_KEY');

// Construct with an API key and locale:
magic = new Magic('PUBLISHABLE_API_KEY', { locale: 'es' });

// Construct with an API key and testMode enabled:
magic = new Magic('PUBLISHABLE_API_KEY', { testMode: true });

// Construct with an API key and defer the loading of the Magic Iframe's assets
magic = new Magic('PUBLISHABLE_API_KEY', { deferPreload: true });

// Construct with an API key plus options:
magic = new Magic('PUBLISHABLE_API_KEY', { network: 'sepolia', endpoint: '...' });

// Construct with API key and custom node options:
const customNodeOptions = {
  rpcUrl: 'https://polygon-rpc.com', // your ethereum, polygon, or optimism mainnet/testnet rpc URL
  chainId: 137 // corresponding chainId for your rpc url
}

magic = new Magic('PUBLISHABLE_API_KEY', {
  network: customNodeOptions, // connected to Polygon Mainnet!
});

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY', { deferPreload: true });

// ...

magic.preload;

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

// log in a user by their email
try {
await magic.auth.loginWithEmailOTP({ email: '[email protected]' });
} catch {
// Handle errors if required!
}

// log in a user by their email, without showing an out-of-the box UI.
try {
await magic.auth.loginWithEmailOTP({ email: '[email protected]', showUI: false });
} catch {
// Handle errors if required!
}

import {
  Magic,
  LoginWithEmailOTPEventOnReceived,
  LoginWithEmailOTPEventEmit,
  RecencyCheckEventOnReceived,
  RecencyCheckEventEmit,
  DeviceVerificationEventEmit,
} from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  // Initiate login flow
  const handle = magic.auth.loginWithEmailOTP({ email: "[email protected]", showUI: false, deviceCheckUI: false });

  handle
  .on(LoginWithEmailOTPEventOnReceived.EmailOTPSent, () => {
    // The email has been sent to the user

    // Prompt the user for the OTP
    const otp = window.prompt('Enter Email OTP');

    // Send the OTP for verification
    handle.emit(LoginWithEmailOTPEventEmit.VerifyEmailOtp, otp);
  })
  .on(LoginWithEmailOTPEventOnReceived.InvalidEmailOtp, () => {
    // User entered invalid OTP

    // Have the user retry entering the OTP and emit via VerifyEmailOtp.
    // You can limit retries and emit Cancel to cancel login flow.

    // cancel login request
    handle.emit(LoginWithEmailOTPEventEmit.Cancel);
  })
  .on('done', (result) => {
    // is called when the Promise resolves

    // convey login success to user
    alert('Login complete!');

    // DID Token returned in result
    const didToken = result;
  })
  .on('error', (reason) => {
    // is called if the Promise rejects
    console.error(reason);
  })
  .on('settled', () => {
    // is called when the Promise either resolves or rejects
  })

  //** MFA Verification Events (if enabled for app)

  .on(LoginWithEmailOTPEventOnReceived.MfaSentHandle, () => {
    // Prompt the user for the MFA TOTP
    const mfa_totp = window.prompt('Enter MFA TOTP');

    // Send the MFA TOTP for verification
    handle.emit(LoginWithEmailOTPEventEmit.VerifyMfaCode, mfa_totp)
  })
  .on(LoginWithEmailOTPEventOnReceived.InvalidMfaOtp, () => {
    // User entered invalid OTP

    // Have the user retry entering the MFA OTP and emit via VerifyMfaCode.
    // You can limit retries and emit Cancel to cancel login flow.

    // cancel login request
    handle.emit(LoginWithEmailOTPEventEmit.Cancel);
  })

  //** Device Verification Events (if enabled for app)

  .on(DeviceVerificationEventOnReceived.DeviceNeedsApproval, () => {
    // is called when device is not recognized and requires approval
  })
  .on(DeviceVerificationEventOnReceived.DeviceVerificationEmailSent, () => {
    // is called when the device verification email is sent
  })
  .on(DeviceVerificationEventOnReceived.DeviceApproved, () => {
    // is called when the device has been approved
  })
  .on(DeviceVerificationEventOnReceived.DeviceVerificationLinkExpired, () => {
    // is called when the device verification link is expired

    // Retry device verification
    handle.emit(DeviceVerificationEventEmit.Retry);
  });

  // LoginWithEmailOTPEventEmit.Cancel can always be emitted to terminate the unresolved request.

} catch (err) {
  // handle errors
}

import { Magic, RPCError, RPCErrorCode } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  await magic.auth.loginWithEmailOTP({ email: '[email protected]' });
} catch (err) {
  if (err instanceof RPCError) {
    switch (err.code) {
      case RPCErrorCode.MagicLinkExpired
      case RPCErrorCode.UserAlreadyLoggedIn:
      // Handle errors accordingly
      break;
    }
  }
}

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

// log in a user by their phone number
try {
  await magic.auth.loginWithSMS({ '+14151231234' });
} catch {
  // Handle errors if required!
}

import { Magic, RPCError, RPCErrorCode } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  await magic.auth.loginWithSMS({ phoneNumber: "+14151231234" });
} catch (err) {
  if (err instanceof RPCError) {
    switch (err.code) {
      case RPCErrorCode.AccessDeniedToUser:
      case RPCErrorCode.MagicLinkRateLimited:
      case RPCErrorCode.UserAlreadyLoggedIn:
      // Handle errors accordingly
      break;
    }
  }
}

import { Magic } from 'magic-sdk';

const magic = new Magic('API_KEY');

// Initiates the flow to update a user's current email to a new one.
try {
  ...
  /* Assuming user is logged in */
  await magic.auth.updateEmailWithUI({ email: '[email protected]' });
} catch {
  // Handle errors if required!
}

/**
 * Initiates the flow to update a user's current email to a new one,
 * without showing an out-of-the box UI.
 */
try {
  /* Assuming user is logged in */
  await magic.auth.updateEmailWithUI({ email: '[email protected]', showUI: false });
} catch {
  // Handle errors if required!
}

import {
  Magic,
  RecencyCheckEventOnReceived,
  RecencyCheckEventEmit,
  UpdateEmailEventOnReceived,
  UpdateEmailEventEmit,
} from "magic-sdk";

const magic = new Magic('API_KEY');

try {
/* Initiates update email flow to update a user's current email to a new one */
const handle = await magic.auth.updateEmailWithUI({
  email: '[email protected]',
  showUI: false,
});

/*
Recency Check Events & Emit
*/

let recencyCheckRetries = 5;

handle
  .on(RecencyCheckEventOnReceived.EmailSent, () => {
    // Email OTP has been sent to the user's primary email

    // Prompt the user for the OTP
    const otp = window.prompt('Primary Email OTP');

    // Send the OTP for verification
    handle.emit(RecencyCheckEventEmit.VerifyEmailOtp, otp);

  })
  .on(RecencyCheckEventOnReceived.PrimaryAuthFactorVerified, () => {
    window.alert('Primary Factor has been verified');
  })
  .on(RecencyCheckEventOnReceived.EmailNotDeliverable, () => {
    // Email OTP was undeliverable to user's primary email

    // Cancel update email request
    handle.emit(RecencyCheckEventEmit.Cancel);
    window.alert('Email Not Deliverable');

  })
  .on(RecencyCheckEventOnReceived.EmailExpired, () => {
    // User entered expired OTP

    handle.emit(RecencyCheckEventEmit.Cancel);
    window.alert('Expired OTP');

  })
  .on(RecencyCheckEventOnReceived.InvalidEmailOtp, () => {
    // User entered invalid OTP; you may limit retries and cancel the request

    if (!recencyCheckRetries) {
      // Cancel update email request
      alert('Too many attempts');
      handle.emit(RecencyCheckEventEmit.Cancel);
    } else {
      const otp = window.prompt(
        `Invalid code, Please enter OTP again. Retries left: ${recencyCheckRetries}`,
      );
      recencyCheckRetries--;

      // Send the OTP for verification
      handle.emit(RecencyCheckEventEmit.VerifyEmailOtp, otp);
    }
  });

/*
Update Email Events & Emit
*/

let updateEmailRetries = 5;

handle
  .on(UpdateEmailEventOnReceived.EmailSent, () => {
    // Email OTP has been sent to the user's secondary email

    // Prompt the user for the OTP
    const otp = window.prompt('Enter new Email OTP');

    // Send the OTP for verification
    handle.emit(UpdateEmailEventEmit.VerifyEmailOtp, otp);
  })
  .on(UpdateEmailEventOnReceived.InvalidEmail, () => {
    // Email OTP was undeliverable to user's secondary email

    const newEmail = window.prompt('Invalid Email, Enter a new Email');

    // Try same or new email address
    handle.emit(
      UpdateEmailEventEmit.RetryWithNewEmail,
      newEmail || email,
    );

  })
  .on(UpdateEmailEventOnReceived.EmailAlreadyExists, () => {
    // Account already exists for new email address

    const newEmail = window.prompt('Email address already in use, Enter a different Email');

    // Try same or new email address
    handle.emit(
      UpdateEmailEventEmit.RetryWithNewEmail,
      newEmail || email,
    );

  })
  .on(UpdateEmailEventOnReceived.InvalidEmailOtp, () => {
    // User entered invalid OTP; you may limit retries and cancel the request

    if (!updateEmailRetries) {
      // Cancel update email request
      alert('Too many attempts');
      handle.emit(UpdateEmailEventEmit.Cancel);
    } else {
      const otp = window.prompt(
        `Invalid code, Please enter OTP again. Retries left: ${updateEmailRetries}`,
      );
      updateEmailRetries--;

      // Send the OTP for verification
      handle.emit(UpdateEmailEventEmit.VerifyEmailOtp, otp);
    }

  })
  .on(UpdateEmailEventOnReceived.EmailUpdated, () => {
    // Update email successful
    alert('Email Updated');
  })

  handle
    .on('error', () => {
      // is called if the Promise rejects
      alert('Error occurred');
    });

try {
  const res = await handle;
  console.log(res);

  // Can also handle successful email update here
alert('Email Updated');
} catch {
  // Handle errors if required!
}

import { Magic, RPCError, RPCErrorCode } from 'magic-sdk';

const magic = new Magic('API_KEY');

try {
  await magic.auth.updateEmailWithUI({ email: '[email protected]', showUI: false });
} catch (err) {
  if (err instanceof RPCError) {
    switch (err.code) {
      case RPCErrorCode.UpdateEmailFailed:
        // Handle errors accordingly
        break;
    }
  }
}

import { Magic } from "magic-sdk"

const accounts = await magic.wallet.connectWithUI();

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

await magic.wallet.showUI()

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

await magic.wallet.showAddress()

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

await magic.wallet.showBalances()

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

await magic.wallet.showNFTs()

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

await magic.wallet.showSendTokensUI()

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

await magic.wallet.showOnRamp()

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

// Assumes a user is already logged in
try {
  const idToken = await magic.user.getIdToken();
} catch {
  // Handle errors if required!
}

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

// Assumes a user is already logged in
try {
  const idToken = await magic.user.generateIdToken({ attachment: 'SERVER_SECRET' });
} catch {
  // Handle errors if required!
}

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

// Assumes a user is already logged in
try {
  const userInfo = await magic.user.getInfo();
} catch {
  // Handle errors if required!
}

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
const isLoggedIn = await magic.user.isLoggedIn();
console.log(isLoggedIn); // => `true` or `false`
} catch {
// Handle errors if required!
}

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  await magic.user.logout();
  console.log(await magic.user.isLoggedIn()); // => `false`
} catch {
  // Handle errors if required!
}

import { Magic } from "magic-sdk";

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  await magic.user.showSettings();
} catch {
  // Handle errors if required!
}

// Deeplink to MFA view
try {
 await magic.user.showSettings({ page: 'mfa' });
} catch {
  // Handle errors if required!
}

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  let handle = magic.user.showSettings({ showUI: false, page: 'recovery' });

  handle.emit(RecoveryFactorEventEmit.StartEditPhoneNumber);
    // Handle start of adding or editing recovery factor phone number

  handle.on(
    RecencyCheckEventOnReceived.PrimaryAuthFactorNeedsVerification, () => {
      // Event triggered if primary auth factor (email) needs verification
    },
  );

  handle.on(RecencyCheckEventOnReceived.EmailSent, () => {
    // Send OTP to email if primary auth factor needs verification
    // Prompt for OTP and emit it to verify primary auth factor

    const code = window.prompt('Please enter the code which was sent to your email');
    handle.emit(RecencyCheckEventEmit.VerifyEmailOtp, code);
  });

  handle.on(RecencyCheckEventOnReceived.PrimaryAuthFactorVerified, () => {
    // Event triggered if email verification success
  });

  handle.on(RecoveryFactorEventOnReceived.EnterNewPhoneNumber, () => {
    // Prompt for secondary factor (phone number) and emit it to send SMS OTP

    const phoneNumber = window.prompt('Enter a phone number');
    handle.emit(RecoveryFactorEventEmit.SendNewPhoneNumber, phoneNumber);
  });

  handle.on(RecoveryFactorEventOnReceived.EnterOtpCode, () => {
    // Prompt for SMS OTP and emit it to verify secondary auth factor

    const otp = window.prompt('Enter SMS OTP');
    handle.emit(RecoveryFactorEventEmit.SendOtpCode, otp);
  });

  handle.on('done', () => {
    // Successfully added secondary recovery factor
  });

  handle.on(RecoveryFactorEventOnReceived.MalformedPhoneNumber, () => {
    // Event triggered if submitted phone number is invalid

    // Prompt for phone number and emit it to send SMS OTP
    // Add your own retry logic to limit retries
    const phoneNumber = window.prompt(
      'You entered an invalid phone number, please try again'
    );
    handle.emit(RecoveryFactorEventEmit.SendNewPhoneNumber, phoneNumber);
  });

  handle.on(RecoveryFactorEventOnReceived.RecoveryFactorAlreadyExists, () => {
    // Event triggered if user is trying to add a phone number that's already in place
  });

  handle.on(RecoveryFactorEventOnReceived.InvalidOtpCode, () => {
    // Event triggered when submitted SMS OTP is invalid

    const code = window.prompt('Invalid OTP code. Please try one more time');
    handle.emit(RecoveryFactorEventEmit.SendOtpCode, code);
  });
} catch {
  // Handle errors if required!
}

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  magic.user.recoverAccount({ email: email })
} catch {
  // Handle errors if required!
}

import { Magic } from 'magic-sdk';
import {
  EnableMFAEventEmit,
  EnableMFAEventOnReceived,
} from '@magic-sdk/types';

const magic = new Magic('PUBLISHABLE_API_KEY');

// user enables MFA through Magic UI
try {
  await magic.user.enableMFA();
} catch {
  // Handle errors if required!
}

// user enables MFA through whitelabel UI
try {
  const handle = magic.user.enableMFA({ showUI: false });

  handle
  .on(EnableMFAEventOnReceived.MFASecretGenerated, ({ QRCode, key }) => {
⁠    // Display QR code
    window.alert(`QRCode: ${QRCode}\nKey:${key}`);

    // Prompt for MFA TOTP and emit it to enable MFA
    const totp = window.prompt('Scan QR code and enter TOTP from MFA app');
    handle.emit(EnableMFAEventEmit.VerifyMFACode, totp);
  })
  .on(EnableMFAEventOnReceived.InvalidMFAOtp, ({ errorCode }) => {
⁠    // User entered invalid MFA TOTP

    // Have the user retry entering the MFA TOTP and emit via VerifyMFACode.
    // You may display error and limit retries by emitting Cancel.
    handle.emit(EnableMFAEventEmit.Cancel);
  })
  .on(EnableMFAEventOnReceived.MFARecoveryCodes, ({ recoveryCode }) => {
    // Enable MFA success, user entered valid MFA TOTP, display Recovery Code
    window.alert(`MFA enabled! Recovery code - ${recoveryCode}`);
  })
  .on('error', (error) => {
⁠    // Handle enable MFA errors
⁠  )};
} catch {
  // Handle errors if required!
}

import { Magic } from 'magic-sdk';
import {
  DisableMFAEventEmit,
  DisableMFAEventOnReceived,
} from '@magic-sdk/types';

const magic = new Magic('PUBLISHABLE_API_KEY');

// user disables MFA through Magic UI
try {
await magic.user.disableMFA();
} catch {
// Handle errors if required!
}

// user disables MFA through whitelabel UI
try {
  const handle = await magic.user.disableMFA({ showUI: false });

  handle
    .on(DisableMFAEventOnReceived.MFACodeRequested, () => {
      // Prompt user for MFA TOTP and emit it to disable MFA
      const totp = window.prompt('Submit MFA TOTP');
      handle.emit(DisableMFAEventEmit.VerifyMFACode, totp);

      // If user lost device and needs to recover with recovery code
      const recoveryCode = window.prompt('Enter Recovery Code');
      handle.emit(DisableMFAEventEmit.LostDevice, recoveryCode);
    })
    .on(DisableMFAEventOnReceived.InvalidMFAOtp, ({ errorCode }) => {
      // Handle user entered invalid MFA TOTP

      // Have the user retry entering the MFA TOTP and emit via VerifyMFACode.
      // You may display error and limit retries by emitting Cancel.
      handle.emit(DisableMFAEventEmit.Cancel);
    })
    .on(DisableMFAEventOnReceived.InvalidRecoveryCode, () => {
      // Handle user entered invalid Recovery Code

      // Have the user retry entering the Recovery Code and emit via LostDevice.
      // You may display error and limit retries by emitting Cancel.
      handle.emit(DisableMFAEventEmit.Cancel);
    })
    .on('done', () => {
      // Handle successful disable MFA
    })
    .on('error', (error) => {
      // Handle disable MFA errors
    });

  const res = await handle;
  console.log(res);
} catch {
  // Handle errors if required!
}

import { Magic } from 'magic-sdk';

const magic = new Magic('PUBLISHABLE_API_KEY');

try {
  await magic.user.revealPrivateKey();
} catch {
  // Handle errors if required!
}

import { Magic } from "magic-sdk";

⁠// Create Magic instance with useStorageCache set to true
const magic = new Magic('PUBLISHABLE_API_KEY', {
  useStorageCache: true
});

magic.user.onUserLoggedOut((isLoggedOut: boolean) => {
  // Do something when user is logged out
  navigation.navigate('LoginScreen')
})

import { Magic } from "magic-sdk";
import { OAuthExtension } from "@magic-ext/oauth2";

const magic = new Magic('PUBLISHABLE_API_KEY', {
  extensions: [new OAuthExtension()],
});

await magic.oauth2.loginWithRedirect({
  provider: '...' /* 'google', 'facebook', 'apple', etc. */,
  redirectURI: 'https://your-app.com/your/oauth/callback',
  scope: ['user:email'] /* optional */,
});

import { Magic } from "magic-sdk";
import { OAuthExtension } from "@magic-ext/oauth2";

const magic = new Magic('PUBLISHABLE_API_KEY', {
  extensions: [new OAuthExtension()],
});

// optionally pass in number to method to set Decentralized ID token lifespan
const result = await magic.oauth2.getRedirectResult();

// Result has the following interface
interface OAuthRedirectResult {
  magic: {
  idToken: string;
  userMetadata: MagicUserMetadata;
},
  oauth: {
  provider: string;
  scope: string[];
  accessToken: string;
  userHandle: string;
  userInfo: ...;
  }
};

import { SDKError } from "magic-sdk";

try {
  // Something async...
} catch (err) {
  if (err instanceof SDKError) {
    // Handle...
  }
}

import { SDKErrorCode } from "magic-sdk";

SDKErrorCode.MissingApiKey;
SDKErrorCode.ModalNotReady;
SDKErrorCode.MalformedResponse;
// and so forth...
// Please reference the `Enum Key` column of the error table below.

import { RPCError } from "magic-sdk";

try {
  // Something async...
} catch (err) {
  if (err instanceof RPCError) {
    // Handle...
  }
}

import { RPCErrorCode } from "magic-sdk";

RPCErrorCode.UserAlreadyLoggedIn;
RPCErrorCode.ParseError;
RPCErrorCode.MethodNotFound;
RPCErrorCode.InternalError;
// and so forth...
// Please reference the `Enum Key` column of the error table below.

import { ExtensionError } from "magic-sdk";

try {
  // Something async...
} catch (err) {
  if (err instanceof ExtensionError) {
    // Handle...
  }
}

const req = magic.auth.loginWithMagicLink({ email: '[email protected]' });

req
  .on('email-sent', () => {/* ... */})
  .then(DIDToken => {/* ... */})
  .once('email-not-deliverable', () => {/* ... */})
  .catch(error => {/* ... */})
  .on('error', error => {/* ... */});

import { Magic } from "magic-sdk";
const magic = new Magic("PUBLISHABLE_API_KEY");

const email = '[email protected]';

if (await magic.user.isLoggedIn()) {
  const didToken = await magic.user.getIdToken();

  // Do something with the DID token.
  // For instance, this could be a `fetch` call
  // to a protected backend endpoint.
  document.getElementById('your-access-token').innerHTML = didToken;
} else {
  // Log in the user
  const user = await magic.auth.loginWithMagicLink({ email });
}