One-time codes (OTP)

Overview

Clerk supports passwordless authentication, which lets users sign in and sign up without having to remember a password. During sign in, users will be asked to enter their identifier (email address or phone number) to receive a one-time code and complete the authentication process.

Arguably, passwordless authentication provides greater security and a better user experience than traditional passwords. However, it is not without its downsides, and often still boils down to the email providers "knowledge based factor" instead of yours.

There are a few different ways to set up passwordless authentication in Clerk; Clerk Hosted Pages, Clerk Components and by creating a custom flow using Clerk's SDKs.

The rest of this guide will explain how to set up passwordless authentication using any of the above methods. Before you start, you will need to configure your instance to allow passwordless sign-ins.

Before you start

• You need to create a Clerk Application in your Clerk Dashboard. For more information, check out our Set up your application guide.
• You need to install Clerk React or ClerkJS to your application.

Configuration

Passwordless authentication can be configured through the Clerk Dashboard. Go to your instance, then User & Authentication > Email, Phone, Username > Authentication factors. Simply choose one of the available passwordless authentication strategies that send one-time codes; Email verification code or SMS verification code.

Don't forget that you also need to make sure you've configured your application instance to request the user's contact information. Users can receive one-time codes via either an email address or a phone number.

Make sure you toggle one of Email address, Phone number on in the Contact information section. Once you've enabled one of the two contact information options, ensure it can be used for identification. Click the cog on the top-right, and verify that the Used for identification toggle is on.

For the rest of this guide, we'll use the Phone number option.

That's all you need to do to enable passwordless authentication with One-time codes for your instance. Now let's see how we can put this configuration to good use.

Using Clerk Hosted Pages

If you're looking for the fastest way to implement passwordless based authentication, you can leverage Clerk Hosted Pages for your sign up, sign in, and user profile pages. You can set these up on your own domain, and match your websites theme with the Clerk Dashboard to create a seamless experience.

You can find your instances in the Paths section of your instance in Clerk Dashboard.

By default, the URLs for your hosted pages will match the following pattern:

https://accounts.[your-domain].com/sign-in
https://accounts.[your-domain].com/sign-up
https://accounts.[your-domain].com/user

Clerk provides SDKs to make navigating to these pages easy.

1
import { 
2
  RedirectToSignUp,
3
  RedirectToSignIn
4
} from "@clerk/clerk-react";
5

6
// Rendering the RedirectToSignOut component will 
7
// cause the browser to navigate to the Sign up 
8
// URL and show the Sign Up Clerk Hosted Page.
9
function App() {
10
  return <RedirectToSignUp />;
11
}
12

13
// Rendering the RedirectToSignIn component will 
14
// cause the browser to navigate to the Sign in 
15
// URL and show the Sign In Clerk Hosted Page.
16
function App() {
17
  return <RedirectToSignIn />;
18
}

1
// redirectToSignIn will cause the browser to
2
// visit the Clerk Hosted Pages Sign in URL.        
3
window.Clerk.redirectToSignIn();
4

5
// redirectToSignIn will cause the browser to
6
// visit the Clerk Hosted Pages Sign in URL.
7
window.Clerk.redirectToSignIn();

Using Clerk Components

You can leverage Clerk Components in order to easily add support for passwordless authentication in your application.

Clerk provides a <SignUp /> pre-built component that renders a sign up form to handle user registrations.

Similarly, there's a <SignIn /> pre-built component that renders a sign in form and takes care of user authentication and session creation.

Note that you don't need to pass any special options to the pre-built <SignUp /> and <SignIn /> components. Passwordless authentication will just work, since you already configured through the Clerk Dashboard.

Sign up using Clerk components

Signing users up to your application is as simple as rendering the <SignUp /> component.

1
import { SignUp } from "@clerk.clerk-react";
2

3
// SignUpPage is your custom sign up page component.
4
function SignUpPage() {
5
  return (
6
    // The Clerk SignUp component needs no special 
7
    // configuration. Passwordless authentication
8
    // will just work when configured from the 
9
    // Clerk dashboard.
10
    <SignUp />
11
  );
12
}

1
<html>
2
<body>
3
    <div id="sign-up"></div>
4
    
5
    <script>
6
        const signUpEl = document.getElementById("sign-up");
7
        // Mount the pre-built Clerk SignUp component
8
        // in an HTMLElement on your page. 
9
        window.Clerk.mountSignUp(signUpEl);
10
        
11
        // Render the SignUp component as a  
12
        // modal on the page.
13
        window.Clerk.openSignUp();
14
    </script>
15
</body>

Sign in using Clerk components

Signing users in with a one-time token is as simple as mounting the <SignIn /> component.

1
import { SignIn } from "@clerk/clerk-react";
2

3
// SignInPage is your custom sign in page component.
4
function SignInPage() {
5
  return (
6
    // The Clerk SignIn component needs no special
7
    // configuration. 
8
    <SignIn />
9
  );
10
}

1
<html>
2
<body>
3
    <div id="sign-in"></div>
4
    
5
    <script>
6
        const signInEl = document.getElementById("sign-in");
7
        // Mount the pre-built Clerk SignIn component
8
        // in an HTMLElement on your page. 
9
        window.Clerk.mountSignIn(signInEl);
10
        
11
        // Render the SignIn component as a 
12
        // modal on the page.
13
        window.Clerk.openSignIn();
14
    </script>
15
</body>

Custom flow

In case one of the above integration methods doesn't cover your needs, you can make use of lower level commands and create a completely custom passwordless authentication flow.

You still need to configure your instance in order to enable passwordless authentication, as described at the top of this guide.

Sign up using custom flow

The passwordless sign up flow is a process which requires users to provide their authentication identifier (email address or phone number) and a one-time code that is sent to them. The important thing to note here is that a user's email address or phone number needs to be verified before the registration is completed.

A successful sign up consists of the following steps:

1. Initiate the sign up process, by collecting the user's identifier (email address or phone number).
2. Prepare the identifier verification.
3. Attempt to complete the identifier verification.

Let's see the above in action. If you want to learn more about sign-ups, check out our documentation on Clerk's Sign up flow.

1
import { useSignUp } from "@clerk/clerk-react";
2

3
function SignUpPage() {
4
    const { signUp } = useSignUp();
5
    
6
    async function onClick(e) {
7
        e.preventDefault();
8
        // Kick off the sign-up process, passing the user's
9
        // phone number.
10
        await signUp.create({
11
            phoneNumber: "+11111111111",
12
        });
13
        
14
        // Prepare phone number verification. An SMS message 
15
        // will be sent to the user with a one-time 
16
        // verification code.
17
        await signUp.preparePhoneNumberVerification();
18
        
19
        // Attempt to verify the user's phone number by 
20
        // providing the one-time code they received.
21
        await signUp.attemptPhoneNumberVerification({
22
            code: "123456",
23
        });    
24
    }
25
    
26
    return (
27
        <button onClick={onClick}>
28
            Sign up without password
29
        </button>
30
    );
31
}

1
const { client } = window.Clerk;
2

3
// Kick off the sign-up process, passing the user's
4
// phone number.
5
const signUp = await client.signUp.create({
6
    phoneNumber: "+11111111111",
7
});
8

9
// Prepare phone number verification. An SMS will 
10
// be sent to the user with a one-time verification 
11
// code.
12
await signUp.preparePhoneNumberVerification();
13

14
// Attempt to verify the user's phone number by providing
15
// the one-time code they received.
16
await signUp.attemptPhoneNumberVerification({
17
    code: "123456",
18
});

You can also verify your users via their email address. There's two additional helper methods, prepareEmailAddressVerification and attemptEmailAddressVerification that work the same way as their phone number counterparts do. You can find more available methods in our ClerkJS API documentation for the SignUp object.

Sign in using custom flow

The passwordless sign in flow is a process which requires users to provide their authentication identifier (email address or phone number) and subsequently a one-time code that is sent to them. We call this one-time code the first factor of authentication.

So, in essence, when you want to authenticate users in your application, you need to

1. Initiate the sign in process, by collecting the user's authentication identifier.
2. Prepare the first factor verification.
3. Attempt to complete the first factor verification.

Let's see the above in action. If you want to learn more about sign ins, check out our documentation on Clerk's Sign in flow.

1
import { useSignIn } from "@clerk/clerk-react";
2

3
function SignInPage() {
4
    const { signIn } = useSignIn();
5
    
6
    async function onClick(e) {
7
        e.preventDefault();
8
        // Kick off the sign-in process, passing the user's 
9
        // authentication identifier. In this case it's their
10
        // phone number.
11
        await signIn.create({ 
12
            identifier: "+11111111111",
13
        });
14

15
        // Prepare first factor verification, specifying 
16
        // the phone code strategy.
17
        await signIn.prepareFirstFactor({ 
18
            strategy: "phone_code", 
19
            phoneNumberId: "idn_1vf1vozUmkg2iN6WY0efWDcEC1a",
20
        });
21

22
        // Attempt to verify the user providing the
23
        // one-time code they received.
24
        await signIn.attemptFirstFactor({
25
            strategy: "phone_code",
26
            code: "123456",
27
        });
28
    }
29
    
30
    return (
31
        <button onClick={onClick}>
32
            Sign in without password
33
        </button>
34
    );
35
}

1
const { client } = window.Clerk;
2
// Kick off the sign-in process, passing the user's 
3
// authentication identifier. In this case it's their
4
// phone number.
5
const signIn = await client.signIn.create({ 
6
    identifier: "+11111111111",
7
});
8

9
// Prepare first factor verification, specifying 
10
// the phone code strategy.
11
await signIn.prepareFirstFactor({ 
12
    strategy: "phone_code", 
13
    phoneNumberId: "idn_1vf1vozUmkg2iN6WY0efWDcEC1a",
14
});
15

16
// Attempt to verify the user providing the
17
// one-time code they received.
18
await signIn.attemptFirstFactor({
19
    strategy: "phone_code",
20
    code: "123456",
21
});

You can also achieve passwordless sign-ins with email address. Simply pass the value email_code as the first factor strategy. Just make sure you've collected the user's email address first. You can find all available methods on the SignIn object documentation.