Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.devGet API keys

Magic Links

Learn how to authenticate or verify users with magic links.

Overview

Clerk supports passwordless authentication with magic links, which lets users sign in and sign up without having to remember a password. During login or registration, users will be asked to enter their email address to receive an email message with a link that can be clicked and complete the authentication process.

This one-click, link based verification method is often referred to as a "magic link". The process is similar to sending a one-time code to your users, but skipping the part where they have to come back to your app and enter the code. This is where the "magic" kicks in.

As a form of passwordless authentication, magic links arguably provide greater security and a better user experience than traditional passwords. Since there's less steps involved in every authentication attempt, the user experience is better than one-time codes. However, magic links are not without their downsides, and often still boil down to the email providers "knowledge based factor" instead of yours.

Magic links are the default passwordless authentication strategy when using Clerk. They can be used to sign up new users, sign in existing ones or allow existing users to verify newly entered email addresses to their profile.

Your users will still be able to choose an alternative authentication (or verification) method even after they've clicked the magic link they received in their inbox. Magic links are simply the default authentication method for email address based, passwordless authentication in Clerk.

Looking for one-time code (OTP) authentication? Check out our One-time code authentication guide.

Magic links can be used to easily authenticate users or verify their email addresses. In all the above cases, Clerk will take care of the plumbing and allow you to offer a seamless experience to your users:

  1. User enters their email address and asks for a magic link.
  2. Your application waits for the verification result.
  3. Clerk sends an email to the user, containing a link to the verification URL.
  4. User clicks the magic link. This can happen on the same device where they entered their email address, or a different device.
  5. Clerk will verify the user's identity and advance any sign in or sign up attempt that might be in progress. In case the verification fails, Clerk will inform the user.
  6. Your user will now be logged in on the device or tab that they opened the link.

Magic links work on any device. There's no constraint on where the link will be opened. For example, a user might try to sign in from their desktop browser, but open the link from their mobile phone.

As an additional security measure, we expire magic links after a while. This way we can guard against cases where a stale link might be compromised. From a user experience perspective, the magic link flow is supposed to be nearly synchronous. Don't worry, your users will have plenty of time to complete the flow before the magic link expires.

Clerk provides a highly flexible API that allows you to hook into any of the above steps, while abstracting away all the complexities of a magic link based authentication or verification flow.

We take care of the boring stuff, like efficient polling, secure session management and different device authentication so you can focus on your application code.

Before you start

Configuration

Magic link authentication can be configured through the Clerk Dashboard. Go to your instance, then User & Authentication > Email, Phone, Username. Simply choose Email verification link as the authentication factor.

Don't forget that you also need to make sure you've configured your application instance to request the user's email address. Users can receive magic links only via email messages. Make sure you toggle Email address on under the Contact information section. You can verify that email addresses will be used for identification, by clicking on the cog next to the Email address option and switching on the Used for identification toggle in the modal.

Don't forget to click on the Apply Changes button at the bottom of the page once you're done configuring your instance.

That's all you need to do to enable authentication with magic links for your instance. Now let's see how we can make some magic with our configuration.

Using Clerk Hosted Pages

If you're looking for the fastest way to implement authentication with magic links, 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 website's theme with the Clerk Dashboard to create a seamless experience.

You can find your instance's sign up and sign in links in the Home 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

For development instances, Clerk will issue you a domain on "lcl.dev". In production, you'll need to supply your own domain. See Production setup or more information.

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
// redirectToSignUp will cause the browser to
2
// visit the Clerk Hosted Pages Sign up URL.
3
window.Clerk.redirectToSignUp();
4
5
// redirectToSignIn will cause the browser to
6
// visit the Clerk Hosted Pages Sign in URL.
7
window.Clerk.redirectToSignIn();

Read our detailed Clerk Hosted Pages guide to learn more.

Using Clerk Components

You can leverage Clerk Components in order to easily add support for magic link based 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.

On the other hand for adding and verifying email addresses to a user's profile, Clerk offers a customizable <UserProfile /> pre-built component.

Note that you don't need to pass any special options to the pre-built <SignUp />,<SignIn /> and <UserProfile /> components. Magic link authentication/verification will just work, since you already configured it 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/nextjs";
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
);
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 magic link is as simple as mounting the <SignIn /> component.

1
import { SignIn } from "@clerk/nextjs";
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
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>

Email address verification using Clerk components

Users can add email addresses through their profile pages and they will be verified via magic links. Simply render the <UserProfile /> component.

1
import { UserProfile } from "@clerk/nextjs";
2
3
// Profile is your custom user profile page component.
4
function Profile() {
5
return (
6
// The Clerk UserProfile component needs no special
7
// configuration.
8
<UserProfile />
9
);
10
}
1
import { UserProfile } from "@clerk/clerk-react";
2
3
// Profile is your custom user profile page component.
4
function Profile() {
5
return (
6
// The Clerk UserProfile component needs no special
7
// configuration.
8
<UserProfile />
9
);
10
}
1
<html>
2
<body>
3
<div id="profile"></div>
4
5
<script>
6
const profileEl = document.getElementById("profile");
7
// Mount the pre-built Clerk UserProfile component
8
// in an HTMLElement on your page.
9
window.Clerk.mountUserProfile(profileEl);
10
</script>
11
</body>

If you're interested in more pre-built offerings, you can read more about Clerk Components.

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 magic link authentication flow.

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

Sign up using custom flow

Registration with magic links follows a set of steps that require users to enter their email address as authentication identifiers and click on a link that's delivered to them via email message.

The sign up process can be completed on the same or a different device. For example, users might enter their email address in their desktop browser, but click the sign up magic link from their mobile phone. The user's email address will still be verified and registration will proceed.

Let's see all the steps involved in more detail.

  • Initiate the sign up process, by collecting the user's identifier. It must be their email address.
  • Start the magic link verification flow. There's two parts to the flow:
    • Prepare a verification for the email address by sending an email with a magic link to the user.
    • Wait until the magic link is clicked. This is a polling behavior which can be cancelled at any time.
  • Handle the magic link verification result accordingly. Note that the magic link can be clicked on a different device/browser than the one which initiated the flow.
    • The verification was successful so you need to continue with the sign up flow.
    • The verification failed or the magic link has expired.

Clerk provides a highly flexible API that allows you to hook into any of the above steps, while abstracting away all the complexities of a magic link based sign up flow.

1
import React from "react";
2
import { useRouter } from "next/router";
3
import {
4
MagicLinkErrorCode,
5
isMagicLinkError,
6
useClerk,
7
useSignUp
8
} from "@clerk/nextjs";
9
10
// pages/sign-up.jsx
11
// Render the sign up form.
12
// Collect user's email address and send a magic link with which
13
// they can sign up.
14
function SignUp() {
15
const [emailAddress, setEmailAddress] = React.useState("");
16
const [expired, setExpired] = React.useState(false);
17
const [verified, setVerified] = React.useState(false);
18
const router = useRouter();
19
const { signUp, setSession } = useSignUp();
20
21
const { startMagicLinkFlow, cancelMagicLinkFlow } =
22
signUp.createMagicLinkFlow();
23
24
async function submit(e) {
25
e.preventDefault();
26
setExpired(false);
27
setVerified(false);
28
29
// Start the sign up flow, by collecting
30
// the user's email address.
31
await signUp.create({ emailAddress });
32
33
// Start the magic link flow.
34
// Pass your app URL that users will be navigated
35
// when they click the magic link from their
36
// email inbox.
37
// su will hold the updated sign up object.
38
const su = await startMagicLinkFlow({
39
redirectUrl: "https://your-app.domain.com/verification",
40
});
41
42
// Check the verification result.
43
const verification = su.verifications.emailAddress;
44
if (verification.verifiedFromTheSameClient()) {
45
setVerified(true);
46
// If you're handling the verification result from
47
// another route/component, you should return here.
48
// See the <MagicLinkVerification/> component as an
49
// example below.
50
// If you want to complete the flow on this tab,
51
// don't return. Check the sign up status instead.
52
return;
53
} else if (verification.status === "expired") {
54
setExpired(true);
55
}
56
57
if (su.status === "complete") {
58
// Sign up is complete, we have a session.
59
// Navigate to the after sign up URL.
60
setSession(
61
su.createdSessionId,
62
() => router.push("/after-sign-up-path"),
63
);
64
return;
65
}
66
}
67
68
if (expired) {
69
return (
70
<div>Magic link has expired</div>
71
);
72
}
73
74
if (verified) {
75
return (
76
<div>Signed in on other tab</div>
77
);
78
}
79
80
return (
81
<form onSubmit={submit}>
82
<input
83
type="email"
84
value={emailAddress}
85
onChange={e => setEmailAddress(e.target.value)}
86
/>
87
<button type="submit">
88
Sign up with magic link
89
</button>
90
</form>
91
);
92
}
93
94
// pages/verification.jsx
95
// Handle magic link verification results. This is
96
// the final step in the magic link flow.
97
function Verification() {
98
const [
99
verificationStatus,
100
setVerificationStatus,
101
] = React.useState("loading");
102
103
const { handleMagicLinkVerification } = useClerk();
104
105
React.useEffect(() => {
106
async function verify() {
107
try {
108
await handleMagicLinkVerification({
109
redirectUrl: "https://redirect-to-pending-sign-up",
110
redirectUrlComplete: "https://redirect-when-sign-up-complete",
111
});
112
// If we're not redirected at this point, it means
113
// that the flow has completed on another device.
114
setVerificationStatus("verified");
115
} catch (err) {
116
// Verification has failed.
117
let status = "failed";
118
if (isMagicLinkError(err) && err.code === MagicLinkErrorCode.Expired) {
119
status = "expired";
120
}
121
setVerificationStatus(status);
122
}
123
}
124
verify();
125
}, []);
126
127
if (verificationStatus === "loading") {
128
return <div>Loading...</div>
129
}
130
131
if (verificationStatus === "failed") {
132
return (
133
<div>Magic link verification failed</div>
134
);
135
}
136
137
if (verificationStatus === "expired") {
138
return (
139
<div>Magic link expired</div>
140
);
141
}
142
143
return (
144
<div>
145
Successfully signed up. Return to the original tab to continue.
146
</div>
147
);
148
}
1
import React from "react";
2
import {
3
BrowserRouter as Router,
4
Routes,
5
Route,
6
useNavigate,
7
} from 'react-router-dom';
8
import {
9
ClerkProvider,
10
ClerkLoaded,
11
MagicLinkErrorCode,
12
isMagicLinkError,
13
UserButton,
14
useClerk,
15
useSignUp,
16
SignedOut,
17
SignedIn,
18
} from '@clerk/clerk-react';
19
20
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
21
22
function App() {
23
return (
24
<Router>
25
<ClerkProvider frontendApi={frontendApi}>
26
<Switch>
27
{/* Root path shows sign up page. */}
28
<Route
29
path="/"
30
element={
31
<>
32
<SignedOut>
33
<SignUpMagicLink />
34
</SignedOut>
35
<SignedIn>
36
<UserButton afterSignOutAllUrl="/" />
37
</SignedIn>
38
</>
39
}
40
/>
41
42
{/* Define a /verification route that handles magic link result */}
43
<Route
44
path="/verification"
45
element={
46
<ClerkLoaded>
47
<MagicLinkVerification />
48
</ClerkLoaded>
49
}
50
/>
51
</Routes>
52
</ClerkProvider>
53
</Router>
54
);
55
}
56
57
// Render the sign up form.
58
// Collect user's email address and send a magic link with which
59
// they can sign up.
60
function SignUpMagicLink() {
61
const [emailAddress, setEmailAddress] = React.useState("");
62
const [expired, setExpired] = React.useState(false);
63
const [verified, setVerified] = React.useState(false);
64
const navigate = useNavigate();
65
const { signUp, setSession } = useSignUp();
66
67
const { startMagicLinkFlow, cancelMagicLinkFlow } =
68
signUp.createMagicLinkFlow();
69
70
async function submit(e) {
71
e.preventDefault();
72
setExpired(false);
73
setVerified(false);
74
75
// Start the sign up flow, by collecting
76
// the user's email address.
77
await signUp.create({ emailAddress });
78
79
// Start the magic link flow.
80
// Pass your app URL that users will be navigated
81
// when they click the magic link from their
82
// email inbox.
83
// su will hold the updated sign up object.
84
const su = await startMagicLinkFlow({
85
redirectUrl: "https://your-app.domain.com/verification",
86
});
87
88
// Check the verification result.
89
const verification = su.verifications.emailAddress;
90
if (verification.verifiedFromTheSameClient()) {
91
setVerified(true);
92
// If you're handling the verification result from
93
// another route/component, you should return here.
94
// See the <MagicLinkVerification/> component as an
95
// example below.
96
// If you want to complete the flow on this tab,
97
// don't return. Check the sign up status instead.
98
return;
99
} else if (verification.status === "expired") {
100
setExpired(true);
101
}
102
103
if (su.status === "complete") {
104
// Sign up is complete, we have a session.
105
// Navigate to the after sign up URL.
106
setSession(
107
su.createdSessionId,
108
() => navigate("/after-sign-up-path"),
109
);
110
return;
111
}
112
}
113
114
if (expired) {
115
return (
116
<div>Magic link has expired</div>
117
);
118
}
119
120
if (verified) {
121
return (
122
<div>Signed in on other tab</div>
123
);
124
}
125
126
return (
127
<form onSubmit={submit}>
128
<input
129
type="email"
130
value={emailAddress}
131
onChange={e => setEmailAddress(e.target.value)}
132
/>
133
<button type="submit">
134
Sign up with magic link
135
</button>
136
</form>
137
);
138
}
139
140
// Handle magic link verification results. This is
141
// the final step in the magic link flow.
142
function MagicLinkVerification() {
143
const [
144
verificationStatus,
145
setVerificationStatus,
146
] = React.useState("loading");
147
148
const { handleMagicLinkVerification } = useClerk();
149
150
React.useEffect(() => {
151
async function verify() {
152
try {
153
await handleMagicLinkVerification({
154
redirectUrl: "https://redirect-to-pending-sign-up",
155
redirectUrlComplete: "https://redirect-when-sign-up-complete",
156
});
157
// If we're not redirected at this point, it means
158
// that the flow has completed on another device.
159
setVerificationStatus("verified");
160
} catch (err) {
161
// Verification has failed.
162
let status = "failed";
163
if (isMagicLinkError(err) && err.code === MagicLinkErrorCode.Expired) {
164
status = "expired";
165
}
166
setVerificationStatus(status);
167
}
168
}
169
verify();
170
}, []);
171
172
if (verificationStatus === "loading") {
173
return <div>Loading...</div>
174
}
175
176
if (verificationStatus === "failed") {
177
return (
178
<div>Magic link verification failed</div>
179
);
180
}
181
182
if (verificationStatus === "expired") {
183
return (
184
<div>Magic link expired</div>
185
);
186
}
187
188
return (
189
<div>
190
Successfully signed up. Return to the original tab to continue.
191
</div>
192
);
193
}
194
195
export default App;
1
const signUp = window.Clerk.client.signUp;
2
const {
3
startMagicLinkFlow,
4
cancelMagicLinkFlow,
5
} = signUp.createMagicLinkFlow();
6
7
const res = await startMagicLinkFlow({
8
// Pass your app URL that users will be navigated
9
// when they click the magic link from their
10
// email inbox.
11
redirectUrl: "https://redirect-from-email-magic-link"
12
});
13
if (res.status === "completed") {
14
// sign up completed
15
} else {
16
// sign up still pending
17
}
18
// Cleanup
19
cancelMagicLinkFlow();

Sign in using custom flow

Signing users in your application is probably the most popular use-case for magic links. Users enter their email address and then click on a link that's delivered to them via email message in order to log in.

The sign in process can be completed on the same or a different device. For example, users might enter their email address in their desktop browser, but click the sign in magic link from their mobile phone. The user's email address will still be verified and authentication will proceed.

Let's see all the steps involved in more detail.

  • Initiate the sign in process, by collecting the user's authentication identifier. It must be their email address.
  • Start the magic link verification flow. There's two parts to the flow:
    • Prepare a verification for the email address by sending an email with a magic link to the user.
    • Wait until the magic link is clicked. This is a polling behavior which can be cancelled at any time.
  • Handle the magic link verification result accordingly. Note that the magic link can be clicked on a different device/browser than the one which initiated the flow.
    • The verification was successful so you need to continue with the sign in flow.
    • The verification failed or the magic link has expired.

Clerk provides a highly flexible API that allows you to hook into any of the above steps, while abstracting away all the complexities of a magic link based sign in flow.

1
// pages/sign-in-with-magic-link.tsx
2
// Initiate a magic link sign in
3
//
4
import type { NextPage } from "next";
5
import { useSignIn, useUser } from "@clerk/nextjs";
6
import { useEffect, useState } from "react";
7
import { EmailCodeFactor } from "@clerk/types";
8
9
const SignInWithMagicLink: NextPage = () => {
10
const { signIn, setSession } = useSignIn();
11
const { user, isLoaded } = useUser();
12
const [expired, setExpired] = useState(false);
13
const [verified, setVerified] = useState(false);
14
15
useEffect(() => {
16
const signInWithMagicLink = async () => {
17
if (!signIn || !setSession || !isLoaded || user) {
18
return;
19
}
20
21
const emailAddress = "john@example.com";
22
const signInResp = await signIn.create({ identifier: emailAddress });
23
const { emailAddressId } = signInResp.supportedFirstFactors.find(
24
(ff) =>
25
ff.strategy === "email_link" && ff.safeIdentifier === emailAddress
26
)! as EmailCodeFactor;
27
28
const { startMagicLinkFlow, cancelMagicLinkFlow } =
29
signIn.createMagicLinkFlow();
30
31
// Start the magic link flow, wait for the link to be clicked, or for expiration.
32
const res = await startMagicLinkFlow({
33
emailAddressId: emailAddressId,
34
redirectUrl: "https://your-app-domain.com/verification",
35
});
36
37
// Check the verification result.
38
const verification = res.firstFactorVerification;
39
if (verification.verifiedFromTheSameClient()) {
40
setVerified(true);
41
} else if (verification.status === "expired") {
42
setExpired(true);
43
}
44
45
await cancelMagicLinkFlow();
46
if (res.status === "complete") {
47
setSession(res.createdSessionId, () => console.log("Now Signed In!"));
48
return;
49
}
50
};
51
52
signInWithMagicLink();
53
}, [signIn]);
54
55
if (user) {
56
return <div>{user.id}</div>;
57
}
58
59
if (expired) {
60
return <div>Magic link has expired</div>;
61
}
62
63
if (verified) {
64
return <div>Signed in on other tab</div>;
65
}
66
67
return <div>Magic Link sent, waiting...</div>;
68
};
69
70
export default SignInWithMagicLink;
71
72
// pages/verification.jsx
73
// Handle magic link verification results. This is
74
// the final step in the magic link flow.
75
function Verification() {
76
const [
77
verificationStatus,
78
setVerificationStatus,
79
] = React.useState("loading");
80
81
const { handleMagicLinkVerification } = useClerk();
82
83
React.useEffect(() => {
84
async function verify() {
85
try {
86
await handleMagicLinkVerification({
87
redirectUrl: "https://redirect-to-pending-sign-in-like-2fa",
88
redirectUrlComplete: "https://redirect-when-sign-in-complete",
89
});
90
// If we're not redirected at this point, it means
91
// that the flow has completed on another device.
92
setVerificationStatus("verified");
93
} catch (err) {
94
// Verification has failed.
95
let status = "failed";
96
if (isMagicLinkError(err) && err.code === MagicLinkErrorCode.Expired) {
97
status = "expired";
98
}
99
setVerificationStatus(status);
100
}
101
}
102
verify();
103
}, []);
104
105
if (verificationStatus === "loading") {
106
return <div>Loading...</div>
107
}
108
109
if (verificationStatus === "failed") {
110
return (
111
<div>Magic link verification failed</div>
112
);
113
}
114
115
if (verificationStatus === "expired") {
116
return (
117
<div>Magic link expired</div>
118
);
119
}
120
121
return (
122
<div>
123
Successfully signed in. Return to the original tab to continue.
124
</div>
125
);
126
}
1
import React from "react";
2
import {
3
BrowserRouter as Router,
4
Routes,
5
Route,
6
useNavigate,
7
} from 'react-router-dom';
8
import {
9
ClerkProvider,
10
ClerkLoaded,
11
MagicLinkErrorCode,
12
isMagicLinkError,
13
UserButton,
14
useClerk,
15
useSignIn,
16
SignedOut,
17
SignedIn,
18
} from '@clerk/clerk-react';
19
20
const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;
21
22
function App() {
23
return (
24
<Router>
25
<ClerkProvider frontendApi={frontendApi}>
26
<Routes>
27
{/* Root path shows sign in page. */}
28
<Route
29
path="/"
30
element={
31
<>
32
<SignedOut>
33
<SignInMagicLink />
34
</SignedOut>
35
<SignedIn>
36
<UserButton afterSignOutAllUrl="/" />
37
</SignedIn>
38
</>
39
}
40
/>
41
42
{/* Define a /verification route that handles magic link result */}
43
<Route
44
path="/verification"
45
element={
46
<ClerkLoaded>
47
<MagicLinkVerification />
48
</ClerkLoaded>
49
} />
50
</Routes>
51
</ClerkProvider>
52
</Router>
53
);
54
}
55
56
// Render the sign in form.
57
// Collect user's email address and send a magic link with which
58
// they can sign in.
59
function SignInMagicLink() {
60
const [emailAddress, setEmailAddress] = React.useState("");
61
const [expired, setExpired] = React.useState(false);
62
const [verified, setVerified] = React.useState(false);
63
const navigate = useNavigate();
64
const { signIn, setSession } = useSignIn();
65
66
const { startMagicLinkFlow, cancelMagicLinkFlow } =
67
signIn.createMagicLinkFlow();
68
69
async function submit(e) {
70
e.preventDefault();
71
setExpired(false);
72
setVerified(false);
73
74
// Start the sign in flow, by collecting
75
// the user's email address.
76
const si = await signIn.create({ identifier: emailAddress });
77
const { emailAddressId } = si.supportedFirstFactors.find(
78
ff => ff.strategy === "email_link" && ff.safeIdentifier === emailAddress
79
);
80
81
// Start the magic link flow.
82
// Pass your app URL that users will be navigated
83
// res will hold the updated sign in object.
84
const res = await startMagicLinkFlow({
85
emailAddressId: email_address_id,
86
redirectUrl: "https://your-app.domain.com/verification",
87
});
88
89
// Check the verification result.
90
const verification = res.firstFactorVerification;
91
if (verification.verifiedFromTheSameClient()) {
92
setVerified(true);
93
// If you're handling the verification result from
94
// another route/component, you should return here.
95
// See the <MagicLinkVerification/> component as an
96
// example below.
97
// If you want to complete the flow on this tab,
98
// don't return. Simply check the sign in status.
99
return;
100
} else if (verification.status === "expired") {
101
setExpired(true);
102
}
103
if (res.status === "complete") {
104
// Sign in is complete, we have a session.
105
// Navigate to the after sign in URL.
106
setSession(
107
res.createdSessionId,
108
() => navigate("/after-sign-in-path"),
109
);
110
return;
111
}
112
}
113
114
if (expired) {
115
return (
116
<div>Magic link has expired</div>
117
);
118
}
119
120
if (verified) {
121
return (
122
<div>Signed in on other tab</div>
123
);
124
}
125
126
return (
127
<form onSubmit={submit}>
128
<input
129
type="email"
130
value={emailAddress}
131
onChange={e => setEmailAddress(e.target.value)}
132
/>
133
<button type="submit">
134
Sign in with magic link
135
</button>
136
</form>
137
);
138
}
139
140
// Handle magic link verification results. This is
141
// the final step in the magic link flow.
142
function MagicLinkVerification() {
143
const [
144
verificationStatus,
145
setVerificationStatus,
146
] = React.useState("loading");
147
148
const { handleMagicLinkVerification } = useClerk();
149
150
React.useEffect(() => {
151
async function verify() {
152
try {
153
await handleMagicLinkVerification({
154
redirectUrl: "https://redirect-to-pending-sign-in-like-2fa",
155
redirectUrlComplete: "https://redirect-when-sign-in-complete",
156
});
157
// If we're not redirected at this point, it means
158
// that the flow has completed on another device.
159
setVerificationStatus("verified");
160
} catch (err) {
161
// Verification has failed.
162
let status = "failed";
163
if (isMagicLinkError(err) && err.code === MagicLinkErrorCode.Expired) {
164
status = "expired";
165
}
166
setVerificationStatus(status);
167
}
168
}
169
verify();
170
}, []);
171
172
if (verificationStatus === "loading") {
173
return <div>Loading...</div>
174
}
175
176
if (verificationStatus === "failed") {
177
return (
178
<div>Magic link verification failed</div>
179
);
180
}
181
182
if (verificationStatus === "expired") {
183
return (
184
<div>Magic link expired</div>
185
);
186
}
187
188
return (
189
<div>
190
Successfully signed in. Return to the original tab to continue.
191
</div>
192
);
193
}
194
195
export default App;
1
const signIn = window.Clerk.client.signIn;
2
const {
3
startMagicLinkFlow,
4
cancelMagicLinkFlow,
5
} = signIn.createMagicLinkFlow();
6
7
const { emailAddressId } = signIn.supportedFirstFactors.find(
8
ff => ff.strategy === "email_link"
9
&& ff.safeIdentifier === "your-users-email"
10
);
11
12
// Pass your app URL that users will be navigated
13
// when they click the magic link from their
14
// email inbox.
15
const res = await startMagicLinkFlow({
16
emailAddressId,
17
redirectUrl: "https://redirect-from-email-magic-link",
18
});
19
if (res.status === "complete") {
20
// sign in completed
21
} else {
22
// sign in still pending
23
}
24
// Cleanup
25
cancelMagicLinkFlow();

Email address verification

Magic links can also provide a nice user experience for verifying email addresses that users add through when updating their profile. The flow is similar to one-time code verification, but users need only click on the magic link; there's no need to return to your app.

  1. Collect the user's email address.
  2. Start the magic link verification flow. There's two parts to the flow:
    1. Prepare a verification for the email address by sending an email with a magic link to the user.
    2. Wait until the magic link is clicked. This is a polling behavior which can be cancelled at any time.
  3. Handle the magic link verification result accordingly. Note that the magic link can be clicked on a different device/browser than the one which initiated the flow.
    1. The verification was successful.
    2. The verification failed or the magic link has expired.

Clerk provides a highly flexible API that allows you to hook into any of the above steps, while abstracting away all the complexities of a magic link based email address verification.

1
import React from "react";
2
import { useUser, useMagicLink } from "@clerk/nextjs";
3
4
// A page where users can add a new email address.
5
function NewEmailPage() {
6
const [email, setEmail] = React.useState('');
7
const [emailAddress, setEmailAddress] = React.useState(null);
8
const [verified, setVerified] = React.useState(false);
9
10
const user = useUser();
11
12
async function submit(e) {
13
e.preventDefault();
14
const res = await user.createEmailAddress({ email });
15
setEmailAddress(res);
16
}
17
18
if (emailAddress && !verified) {
19
return (
20
<VerifyWithMagicLink
21
emailAddress={emailAddress}
22
onVerify={() => setVerified(true)}
23
/>
24
);
25
}
26
27
return (
28
<form onSubmit={submit}>
29
<input
30
type="email"
31
value={email}
32
onChange={e => setEmail(e.target.value)}
33
/>
34
</form>
35
);
36
}
37
38
// A page which verifies email addresses with magic links.
39
function VerifyWithMagicLink({
40
emailAddress,
41
onVerify,
42
}) {
43
const { startMagicLinkFlow } = useMagicLink(emailAddress);
44
45
React.useEffect(() => {
46
verify();
47
}, []);
48
49
async function verify() {
50
// Start the magic link flow.
51
// Pass your app URL that users will be navigated
52
// when they click the magic link from their
53
// email inbox.
54
const res = await startMagicLinkFlow({
55
redirectUrl: "https://redirect-from-email-magic-link",
56
});
57
58
// res will hold the updated EmailAddress object.
59
if (res.verification.status === "verified") {
60
onVerify();
61
} else {
62
// act accordingly
63
}
64
}
65
66
return (
67
<div>
68
Waiting for verification...
69
</div>
70
);
71
}
1
import React from "react";
2
import { useUser, useMagicLink } from "@clerk/clerk-react";
3
4
// A page where users can add a new email address.
5
function NewEmailPage() {
6
const [email, setEmail] = React.useState('');
7
const [emailAddress, setEmailAddress] = React.useState(null);
8
const [verified, setVerified] = React.useState(false);
9
10
const user = useUser();
11
12
async function submit(e) {
13
e.preventDefault();
14
const res = await user.createEmailAddress({ email });
15
setEmailAddress(res);
16
}
17
18
if (emailAddress && !verified) {
19
return (
20
<VerifyWithMagicLink
21
emailAddress={emailAddress}
22
onVerify={() => setVerified(true)}
23
/>
24
);
25
}
26
27
return (
28
<form onSubmit={submit}>
29
<input
30
type="email"
31
value={email}
32
onChange={e => setEmail(e.target.value)}
33
/>
34
</form>
35
);
36
}
37
38
// A page which verifies email addresses with magic links.
39
function VerifyWithMagicLink({
40
emailAddress,
41
onVerify,
42
}) {
43
const { startMagicLinkFlow } = useMagicLink(emailAddress);
44
45
React.useEffect(() => {
46
verify();
47
}, []);
48
49
async function verify() {
50
// Start the magic link flow.
51
// Pass your app URL that users will be navigated
52
// when they click the magic link from their
53
// email inbox.
54
const res = await startMagicLinkFlow({
55
redirectUrl: "https://redirect-from-email-magic-link",
56
});
57
58
// res will hold the updated EmailAddress object.
59
if (res.verification.status === "verified") {
60
onVerify();
61
} else {
62
// act accordingly
63
}
64
}
65
66
return (
67
<div>
68
Waiting for verification...
69
</div>
70
);
71
}
1
const user = window.Clerk.user;
2
const emailAddress = user.emailAddresses[0];
3
const {
4
startMagicLinkFlow,
5
cancelMagicLinkFlow,
6
} = emailAddress.createMagicLinkFlow();
7
8
// Pass your app URL that users will be navigated
9
// when they click the magic link from their
10
// email inbox.
11
const res = await startMagicLinkFlow({
12
redirectUrl: "https://redirect-from-email-magic-link",
13
});
14
if (res.verification.status === "verified") {
15
// email address was verified
16
} else {
17
// email address wasn't verified
18
}
19
// Cleanup
20
cancelMagicLinkFlow();

Was this helpful?

Clerk © 2022