Initial Setup

Overview

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

Before You Start

important

These intructions assume that you already have gone through our 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 will receive the credentials from your app. You can choose between email, phone number or both (the user will have to choose one during the login flow).
• Flow Type: This is the actual credential type that the will be used for authentication. You can choose between Magic Link, OTP (One-Time Password), or both (the user will have to choose on 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 config 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/app-info
        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 your application.

In order for the Pre Built UI to be rendered inside your application, will will have to specify which routes will 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 will have to intialize the Backend SDK alongside the code that starts your server. The init call will include configuration details for your app, how the backend will connect to the SuperTokens Core, as well as the Recipes that will be used in your setup.

For the Passwordless recipe, you will also need to specify the flowType and contactMethod. Just click one of the options from the next form and the code snippet will get updated.

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/app-info
        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

Now that you have completed the main setup you can explore more advanced topics related to the Passwordless recipe.

Authentication Flow Callbacks

Add custom logic after the logs in or signs up.

Customize the Magic Link

Change how Magic Links are constructed.

OTP Customization

Change the format of the generated One-Time Password.

Email Delivery

Customize how emails are sent to your users.

SMS Delivery

Customize how SMS messages are sent to your users.