Skip to main content

Magic Link

Allows users to connect to your app using Magic Auth or Magic Connect

Magic is a developer SDK that integrates with your application to enable passwordless Web3 onboarding (no seed phrases) and authentication using magic links

Usage​

Magic offers two flavors of our SDK: Magic Connect, which provides a plug-and-play experience, and Magic Auth, a customizable white-labeled wallet solution.

Magic Auth

Login with Email or Phone Number​

With below configuration, users will be able to log in using their email or phone number.

If you want to restrict login via email only - pass smsLogin:false. If you want to restrict login via phone number only - pass emailLogin:false to the MagicLink constructor.

import { MagicLink } from "@thirdweb-dev/wallets";

const wallet = new MagicLink({
  apiKey: "YOUR_API_KEY",
  type: "auth",
});

// connect with email or phone number

await wallet.connect({
  email: "user@example.com",
});

// OR

await wallet.connect({
  phoneNumber: "+123456789",
});

Social Login​

import { MagicLink } from "@thirdweb-dev/wallets";

const wallet = new MagicLink({
  apiKey: "YOUR_API_KEY",
  type: "auth",

  // specify which Oauth providers to enable
  // and the URI to redirect to after the oauth flow is complete
  oauthOptions: {
    redirectURI: "https://example.com/foobar",
    providers: ["google", "facebook"],
  },
});

// connect with a oauth provider
await magic.connect({
  oauthProvider: "google",
});
Magic Connect 
import { MagicLink } from "@thirdweb-dev/wallets";

const wallet = new MagicLink({
  apiKey: "YOUR_API_KEY",
  type: "connect",
});

await wallet.connect();

Configuration​

Provide a configuration object when instantiating the MagicLink class.

apiKey (required)

Your Magic Link apiKey. You can get an API key by signing up for an account on Magic Link's website.

Must be a string.

clientId (recommended)

Provide clientId to use the thirdweb RPCs for given chains

You can create a client ID for your application from thirdweb dashboard.

type (optional)

Whether to use Magic Auth or Magic Connect to connect to the wallet.

Default is "auth".

type: "auth" | "connect";
magicSdkConfiguration (optional)

Configuration for Magic Auth SDK.

This is only relevant if you are using type: 'auth'.

{
  locale?: string;
  endpoint?: string;
  testMode?: boolean;
}
locale (optional)

Customize the language of Magic's modal, email and confirmation screen. See Localization for more.

endpoint (optional)

A URL pointing to the Magic iframe application.

testMode (optional)

Enable testMode to assert the desired behavior through the email address so that you don't have to go through the auth flow.

smsLogin (optional)

Specify whether you want to allow users to log in with their phone number or not. It is true by default

This is only relevant if you are using type: 'auth'.

Must be a boolean.

emailLogin (optional)

Specify whether you want to allow users to log in with their email or not. It is true by default

This is only relevant if you are using type: 'auth'.

Must be a boolean.

oauthOptions (optional)

Specify which oauth providers you support in providers array.

Specify which URI to redirect to after the oauth flow is complete in redirectURI option. If no redirectURI is specified, the user will be redirected to the current page.

caution

You must pass full URL and not just a relative path. For example, "https://example.com/foo" is valid but "/foo" is not. You can use new URL("/foo", window.location.origin).href to get the full URL from a relative path based on the current origin.

This is only relevant if you are using type: 'auth'.

You also need to enable the oauth providers for your apiKey from Magic dashboard.

Type​

type OauthOptions = {
  redirectURI?: string;
  providers: OauthProvider[];
};

type OauthProvider =
  | "google"
  | "facebook"
  | "apple"
  | "github"
  | "bitbucket"
  | "gitlab"
  | "linkedin"
  | "twitter"
  | "discord"
  | "twitch"
  | "microsoft";

Example​

const wallet = new MagicLink({
  apiKey: "YOUR_API_KEY",
  type: "auth",
  // specify which Oauth providers to enable
  oauthOptions: {
    redirectURI: new URL("/foo", window.location.origin).href,
    providers: ["google", "facebook", "github", "bitbucket"],
  },
});
chains (optional)

Provide an array of chains you want to support.

Must be an array of Chain objects, from the @thirdweb-dev/chains package.

walletStorage (optional)

The wallet needs to store some data in persistent storage. By default localStorage is used. If you want to use a different storage, you can pass it in the walletStorage option.

Must be an object conforming to the AsyncStorage interface:

export interface AsyncStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

import { MagicLink } from "@thirdweb-dev/wallets";

const wallet = new MagicLink({
  // ... other required config

  walletStorage: {
    getItem: (key) => {
      // Implement your own storage logic here
    },
    removeItem: (key) => {
      // Implement your own storage logic here
    },
    setItem: (key, value) => {
      // Implement your own storage logic here
    },
  },
});

Methods​

Inherits all the public methods from the AbstractClientWallet class.

connect​

Magic Auth

There are three ways to call the connect function - email or phoneNumber or oauthProvider

email

This opens the Magic Link's Modal and prompts the user to click on the link sent to their email.

await wallet.connect({
  email: "user@example.com",
});
phoneNumber

This opens the Magic Link's Modal and prompts the user to enter the OTP sent to their phone via SMS.

await wallet.connect({
  phoneNumber: "+123456789",
});
oauthProvider

This redirects the user to given provider's sign-in page and once the user is authenticated, it redirects the user back to the redirectURI provided in MagicLink constructor.

await magic.connect({
  oauthProvider: "google",
});

Additional Configuration​

wallet.connect({
  chainId: 5,
});

If chainId is provided, the wallet will be connected to the network with the given chainId, else it will be connected to the Ethereum Mainnet.

Magic Connect

You can call the connect function without any arguments. Calling connect opens the Magic Link's Modal and prompts the user to login via Google or email.

await wallet.connect();

Additional Configuration​

wallet.connect({
  chainId: 5,
});

If chainId is provided, the wallet will be connected to the network with the given chainId, else it will be connected to the Ethereum Mainnet.

getMagic​

Get Magic Auth SDK instance. Learn more about Magic Auth SDK

you use all methods available in the Magic Auth SDK from the SDK instance. Refer to Magic Auth API for more details.

const magicSDK = await wallet.getMagic();
Configuration

Return Value​

Returns the magic auth SDK instance of type InstanceWithExtensions<SDKBase, OAuthExtension[]>

InstanceWithExtensions<SDKBase, OAuthExtension[]>;