Initial setup

Add Passwordless authentication to your project using Prebuilt or Custom UI components.

Overview

This page shows you how to add the Passwordless recipe to your project. The tutorial creates a login flow, rendered by either the Prebuilt UI components or by your own Custom UI.

Before you start

important

These instructions assume that you already have gone through the main quickstart guide. If you have skipped that page please follow the tutorial and return here once you're done.

Terminology

Before going into the actual steps lets first talk about two terms that influence how you configure the Passwordless recipe.

• Contact Method: This defines how the user receives the credentials from your app. You can choose between email, phone number or both (the user has to choose one during the login flow).
• Flow Type: This is the actual credential type used for authentication. You can choose between Magic Link, OTP (One-Time Password), or both (the user has to choose one during the login flow).

Steps

What type of UI are you using?

1. Initialize the frontend SDK

1.1 Add the Passwordless recipe in your main configuration file.

import React from 'react';

import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import Passwordless from "supertokens-auth-react/recipe/passwordless";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    appInfo: { 
        // learn more about this on https://supertokens.com/docs/references/frontend-sdks/reference#sdk-configuration
        appName: "<YOUR_APP_NAME>",
        apiDomain: "<YOUR_API_DOMAIN>",
        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
        apiBasePath: "/auth",
        websiteBasePath: "/auth",
    },
    recipeList: [
        Passwordless.init({
            contactMethod: "PHONE"
        }),
        Session.init()
    ]
});

1.2 Include the pre-built UI components in your application.

To render the Pre-Built UI inside your application, you need to specify which routes show the authentication components. The React SDK uses React Router under the hood to achieve this. Based on whether you already use this package or not in your project, there are two different ways of configuring the routes.

Do you use react-router-dom?

import React from 'react';
import {
  BrowserRouter,
  Routes,
  Route,
  Link
} from "react-router-dom";

import { PasswordlessPreBuiltUI } from 'supertokens-auth-react/recipe/passwordless/prebuiltui';
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react/ui";
import * as reactRouterDom from "react-router-dom";

class App extends React.Component {
    render() {
        return (
            <SuperTokensWrapper>
                <BrowserRouter>
                    <Routes>
                        {/*This renders the login UI on the /auth route*/}
                        {getSuperTokensRoutesForReactRouterDom(reactRouterDom, [PasswordlessPreBuiltUI])}
                        {/*Your app routes*/}
                    </Routes>
                </BrowserRouter>
            </SuperTokensWrapper>
        );
    }
}

important

If you are using useRoutes, createBrowserRouter or have routes defined in a different file, you need to adjust the code sample. Please see this issue for further details.

import React from 'react';

import { BrowserRouter, useRoutes } from "react-router-dom";
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react/ui";
import * as reactRouterDom from "react-router-dom";

function AppRoutes() {
  const authRoutes = getSuperTokensRoutesForReactRouterDom(
    reactRouterDom,
    [/* Add your UI recipes here e.g. EmailPasswordPrebuiltUI, PasswordlessPrebuiltUI, ThirdPartyPrebuiltUI */]
  );

  const routes = useRoutes([
    ...authRoutes.map(route => route.props),
    // Include the rest of your app routes 
  ]);

  return routes;
}

function App() {
  return (
    <SuperTokensWrapper>
      <BrowserRouter>
          <AppRoutes />
      </BrowserRouter>
    </SuperTokensWrapper>
  );
}

2. Initialize the backend SDK

You need to initialize the Backend SDK alongside the code that starts your server. The init call includes configuration details for your app. It specifies how the backend connects to the SuperTokens Core, as well as the Recipes used in your setup.

For the Passwordless recipe, you also need to specify the flowType and contactMethod. Click one of the options from the next form and the code snippet updates.

Backend SDK Init

import supertokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import Passwordless from "supertokens-node/recipe/passwordless";

supertokens.init({
    // Replace this with the framework you are using
    framework: "express",
    supertokens: {
        // We use try.supertokens for demo purposes.
        // At the end of the tutorial we will show you how to create
        // your own SuperTokens core instance and then update your config.
        connectionURI: "https://try.supertokens.io",
        // apiKey: <YOUR_API_KEY>
    },
    appInfo: {
        // learn more about this on https://supertokens.com/docs/references/backend-sdks/reference#sdk-configuration
        appName: "<YOUR_APP_NAME>",
        apiDomain: "<YOUR_API_DOMAIN>",
        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
        apiBasePath: "/auth",
        websiteBasePath: "/auth",
    },
    recipeList: [
        Passwordless.init({
            flowType: "MAGIC_LINK",
            contactMethod: "PHONE"
        }),
        Session.init() 
    ]
});

Next steps

Having completed the main setup, you can explore more advanced topics related to the Passwordless recipe.

Customize the Magic Link

Change how Magic Links get created.

OTP Customization

Change the format of the generated One-Time Password.

Hooks and overrides

Add custom logic after the logs in or signs up.

Email Delivery

Customize how emails get delivered to your users.

SMS Delivery

Customize how SMS messages get delivered to your users.