Quickstart

Overview

This page shows you how to add the Passkeys authentication method 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

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.

Restrictions

At the moment, the authentication method is only available in the Node.js SDK.

Steps

1. Initialize the frontend SDK

What type of UI are you using?

1.1 Add the WebAuthn recipe in your main configuration file.

import React from 'react';

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

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        websiteDomain: "...",
        appName: "...",
    },
    recipeList: [
        WebAuthn.init(),
        Session.init()
    ]
});

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

In order for the pre-built UI to render inside your application, you have 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 { WebauthnPreBuiltUI } from 'supertokens-auth-react/recipe/webauthn/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, [WebauthnPreBuiltUI])}
                        {/*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

Initialize the backend SDK and include the WebAuthn recipe. 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.

The recipe exposes the required endpoints that get accessed by the frontend code, and communicates with the SuperTokens Core to complete the authentication flow. You can configure different aspects of the recipe's behavior but, for the completion of this guide, use the default values. After you confirm that the flow works as expected you can explore more advanced customisations options.

import supertokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import WebAuthN from "supertokens-node/recipe/webauthn";

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: {
        appName: "<YOUR_APP_NAME>",
        apiDomain: "<YOUR_API_DOMAIN>",
        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
        apiBasePath: "/auth",
        websiteBasePath: "/auth",
    },
    recipeList: [
        WebAuthN.init(),
        Session.init()
    ]
});

Next steps

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

Backend Recipe Configuration

Read through the configuration options for the backend recipe.

Customize Credentials Generation

See how you can adjust the process that generates credentials.

Customize Credentials Validation

Discover how to customize the validation process.

Email Delivery

Customize the email sending process.