Magic links overview

Let your users sign up or log in to your app or website by entering their email address. They only need to click once on a submit button. You can own the UI or use Stytch's customizable, drop-in components.

Managing user login with Stytch enables you to authenticate users on an ongoing basis via one-click, passwordless login. When a user signs up for your app, you'll add them to Stytch. Then, whenever a user goes to login to your app, authenticate them via a magic link.

This is an integration guide for setting up the Stytch SDK in your app. First, you'll configure our frontend SDK in your client code to create a login experience in your app. Then, you'll add support to your server code for authenticating Stytch magic links. If you have any questions, check out the docs for the SDK or our example app that uses the code in this guide.

1. Step 1: Configure your project in the Stytch dashboard

   Before adding Email magic links to your application you will need to make the following project configurations within the Stytch dashboard:

   1. Create a Login and Sign-up redirect URL on the redirect URL configuration page.

   2. Within SDK Configuration, authorize the domain(s) (eg. http://localhost:3000) the SDK will run on. Under Auth methods enable the Email magic links > Enable the LoginOrCreate Flow toggle.

   3. Finally, under API keys, save your project's public_token for later.

2. Step 2: Use Stytch

   2.1 Install Stytch

   Install the @stytch/vanilla-js packages via npm or yarn. The packages provides frontend support for the Javascript SDK.

   npm install @stytch/vanilla-js --save

   2.2 Create Stytch Client

   Initialize the Stytch Client

   <script>
   import { StytchUIClient } from '@stytch/vanilla-js';
   const stytch = new StytchUIClient('PUBLIC_TOKEN');
   </script>
   
   <div id="stytch-login-ui"></div>
   

   2.3 Configure your Login Component

   Create a config object to initalize the magic link product in the JavaScript SDK.

   <script>
   import { StytchUIClient, Products } from '@stytch/vanilla-js';
   const stytch = new StytchUIClient('PUBLIC_TOKEN');
   const config = {
     emailMagicLinksOptions: {
       loginExpirationMinutes: 30,
       loginRedirectURL: 'https://example.com/authenticate',
       signupExpirationMinutes: 30,
       signupRedirectURL: 'https://example.com/authenticate',
     },
     products: [
       Products.emailMagicLinks,
     ],
   };
   stytch.mountLogin({ elementId: "stytch-login-ui", config })
   </script>
   
   <div id="stytch-login-ui"></div>
   

   2.4 Customize your Login Component

   Customize the style of the SDK. The style object allows you to modify the look and feel to match your app.here.

   <script>
   import { StytchUIClient, Products } from '@stytch/vanilla-js';
   const stytch = new StytchUIClient('PUBLIC_TOKEN');
   const config = {
     emailMagicLinksOptions: {
       loginExpirationMinutes: 30,
       loginRedirectURL: 'https://example.com/authenticate',
       signupExpirationMinutes: 30,
       signupRedirectURL: 'https://example.com/authenticate',
     },
     products: [
       Products.emailMagicLinks,
     ],
   };
   
   const styles = {
     fontFamily: '"Helvetica New", Helvetica, sans-serif',
   };
   
   stytch.mountLogin({ elementId: "stytch-login-ui", styles, config })
   </script>
   
   <div id="stytch-login-ui"></div>
   

3. Step 3: Add server side support to your app for Stytch

   Stytch works best with support from your app's server. You'll need to create or modify a few endpoints. The Node examples use express to create http endpoints and express-session for sessions, but they can be replaced with any other http framework.

   3.1 Install Stytch

   Install the stytch package via npm or yarn. The stytch package provides backend support for the Stytch API.

   npm install stytch --save

   3.2 Create a user

   POST/PUT user endpoint: When a user logs in to your app for the first time, the SDK will create a Stytch user for them and return a userId. We recommend adding a stytchUserId field to your user to save it.

   app.post('/users', function (req, res) {
     var stytchUserId = req.body.userId;
     // TODO: Save stytchUserId with your user record in your app's storage
     res.send(`Created user with stytchUserId: ${stytchUserId}`);
   });

   3.3 Authenticate a user: GET route

   GET authentication endpoint: When a user enters their email and clicks the login button, we will send them an email with a magic link to log in. You need to create a route for the magic link. There are a few ways to do this:

   • - Implement a GET route on your frontend that accepts a token and passes it to a route on your backend that passes the token to Stytch to authenticate. This is recommended if your frontend lives separately from your backend.
   • - Implement a GET route in your backend that accepts a token and passes it to Stytch to authenticate. This is recommended if your backend and frontend live in the same service.

   3.4 Authenticate a user: POST route

   POST to Stytch: If your url in the previous step was https://example.com, your user will be directed to https://example.com?token={token} when they click the magic link in the email. You'll pass this token to Stytch to authenticate it. If authentication is successful, create a user session and log them into your app. If you'd like to keep this user logged-in for a while, include "session_duration_minutes": 60 (an hour, for example). Check out the session management guide to learn how to handle the session.

   const stytch = require('stytch');
   const client = new stytch.Client({
     project_id: "PROJECT_ID",
     secret: "SECRET",
     env: stytch.envs.test
   });
   app.get('/authenticate', function (req, res) {
     var token = req.query.token;
     client.magicLinks.authenticate(token)
     .then(response => {
       req.session.authenticated = true;
         req.session.save(function(err) {
       console.log(err);
       });
       res.redirect('/home')
     })
     .catch(error => {
       console.log(error);
       res.send('There was an error authenticating the user.');
     });
   });

1. Step 1: Create a password reset UI

   Here's an example of a password reset component.

   

2. Step 2: Add redirect URLs to the Stytch dashboard

   Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.

   By default, all redirect URLs are set to http://localhost:3000 for the Test environment.

3. Step 3: Create user

   To send a login email, the user who forgot their password needs to be created with Stytch. Check if the user has a Stytch user ID. If they do not, create a Stytch user for them and save the user ID from the response. This needs to happen once for each user who forgets their password. We recommend saving the Stytch user ID in a new column of your users table or within a new table linking your users with their Stytch user ID.

   curl --request POST \
   	--url https://test.stytch.com/v1/users \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   		"email": "sandbox@stytch.com"
   	}'

4. Step 4: Send magic link

   When the user wants to reset their password, send a request to send an email magic link. Either the login_magic_link_url or signup_magic_link_url request parameter is the URL the user will be redirected to from the email. The signup_magic_link_url will be used if the user is in a pending state due to using CreateUser's create_user_as_pending request parameter.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/email/send \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   		"email": "sandbox@stytch.com",
   		"login_magic_link_url": "https://example.com/login",
   		"signup_magic_link_url": "https://example.com/signup"
   	}'

5. Step 5: Authenticate magic link

   When the user opens the email, they are prompted to log in by clicking either the login_magic_link_url or signup_magic_link_url from the SendMagicLinkByEmail request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. If the response is a 200, you have successfully verified ownership of the user's email address. That authentication event allows you to provide the user with access to their logged-in profile. While it's not necessary from an authentication perspective at this point, you may also allow them to rotate their password if that's their preference.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/authenticate \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   	  "token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
   	}'

1. Step 1: Build an invite user UI

   If you don't already have one, you'll need to build an invite user view for your app.

   

2. Step 2: Add redirect URLs to the Stytch dashboard

   Add the invite URL to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.

   By default, all redirect URLs are set to http://localhost:3000 for the Test environment.

3. Step 3: Invite user

   When you want to send an invitation to a user, send a InviteByEmail request. The user will receive an email explaining they've been invited. This will create a Stytch user with an invited status. Remember to save the user ID from the response. The invite_magic_link_url request parameter is the URL the user will be redirected to from the email.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/email/invite \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   		"email": "sandbox@stytch.com",
   		"invite_magic_link_url": "https://example.com/authenticate"
   	}'

4. Step 4: Authenticate magic link

   When the user opens the email, they are prompted to log in for the first time by clicking the provided invite_magic_link_url from the InviteByEmail request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. The user’s status will be set to active as well. If the response is a 200, the user is verified and can be logged in.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/authenticate \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   	  "token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
   	}'

5. Step 5: Later authentication

   After the user has accepted their invitation, you can send a magic link to authenticate a user by sending a SendMagic request.

1. Step 1: Update your login UI

   Here's an example of a login component when Stytch is the only login method.

   

2. Step 2: Create user

   Since each user needs to be created with Stytch, check if the user logging in or signing up has a Stytch user ID. If they do not, create a Stytch user for them and save the user ID from the response. This needs to happen once per user. We recommend saving the Stytch user ID in a new column of your users table or within a new table linking your users with their Stytch user ID.

   curl --request POST \
   	--url https://test.stytch.com/v1/users \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   		"email": "sandbox@stytch.com"
   	}'

3. Step 3: Add redirect URLs to the Stytch dashboard

   Add the login and signup URLs to the project's list of predefined redirect URLs in the dashboard. For more information on why this step is necessary, please check out the documentation here.

   By default, all redirect URLs are set to http://localhost:3000 for the Test environment.

4. Step 4: Send magic link

   When a user wants to login using Stytch, send a request to send an email magic link. If a user is signing up for the first time, you can send this request after receiving the user ID from the CreateUser response. Either the login_magic_link_url or signup_magic_link_url request parameter is the URL the user will be redirected to from the email. The signup_magic_link_url will be used if the user is in a pending state due to using CreateUser's create_user_as_pending request parameter.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/email/send \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   		"email": "sandbox@stytch.com",
   		"login_magic_link_url": "https://example.com/login",
   		"signup_magic_link_url": "https://example.com/signup"
   	}'

5. Step 5: Authenticate magic link

   When the user opens the email, they are prompted to log in by clicking either the login_magic_link_url or signup_magic_link_url from the SendMagicLinkByEmail request. The url will contain a token in the query params that you will use to send the AuthenticateMagic request. If the response is a 200, the user is verified and can be logged in.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/authenticate \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   	  "token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
   	}'

1. Step 1: Confirm PKCE makes sense for your application

   PKCE provides cryptographic assurance that a login flow starts and ends on the same device. While this is almost always a desired property, there is one notable exception to the rule: mobile webviews. Consider the following scenario:

   1. A user sees a link to your application embedded in another mobile application, such as Twitter or Slack.
   2. The user clicks the link and the application is opened inside a webview owned by the parent application.
   3. The user is logged out by default, because cookies and session state are not shared between webviews and the native mobile browser.
   4. The user attempts to log in via an email magic link. The PKCE code_verifier is generated, and stored inside the webview.
   5. The user leaves the initial webview and opens their email application. They click the magic link in the email, and your application is opened again, this time in the native mobile browser.
   6. Your application attempts to submit the magic link token, but does not have access to the original code_verifier. The user fails to log in with a pkce_expected_code_verifier error, and needs to request a new magic link from the native mobile browser.
   Depending on your application's userbase, mobile webviews could make up for a significant amount of traffic, and PKCE would add friction to that user experience. For cases like these, you might choose to omit PKCE and supplement your login flow with a second factor like SMS or WebAuthn instead.
   
   If your application caters to desktop users, native apps, or is not shared on social media, you can implement PKCE with confidence.

2. Step 2: Enable PKCE for Magic Links

   First, enable PKCE for the JavaScript SDK. In order to do so, toggle the option in the SDK Configuration page of the Stytch dashboard. Once this configuration is set, the SDK will automatically start applying PKCE to all magic link login flows it creates.

3. Step 3: Send the Magic Link

   Call the magicLinks.email.loginOrCreate() method to start the magic link flow. The SDK will generate a code_verifier and store it in local storage before asking Stytch to send the email. If you use the SDK's built in Magic Link UI this step is already handled for you.

   function SendMagicLink({ email }) {
     const stytch = useStytch();
     const startMagicLinkFlow = useCallback(
       () => stytch.magicLinks.email.loginOrCreate(email), 
       [stytch]);
   
     return (
       <button onClick={startMagicLinkFlow}>
         Click here to send a magic link to {email}
       </button>
     );   
   }
   

4. Step 4: Authenticate the Magic Link token

   At the route that the user is redirected to after the Magic Link flow, pull the token out of the URL params and call magicLinks.authenticate(token) to exchange the token for a Stytch session. The SDK will automatically retrieve the code_verifier created earlier from local storage and pass it on to the Stytch servers.

   function MagicLinkCallback() {
     const stytch = useStytch();
   
     useEffect(() => {
       const params = new URLSearchParams(window.location.search);
       const token = params.get('token');
       if(!token) {
         // TODO: Redirect back to logged-out view 
       }
       stytch.magicLinks.authenticate(token, {
         session_duration_minutes: 60,
       }).then(() => {
         // TODO: Redirect to final logged-in view
       })
     }, [stytch]);
   
     return (
       <div>
         Authenticating....
       </div>
     );   
   }
   

5. Step 5: You're Done!

   You just finished all the critical components to authenticate your users via magic links with PKCE! Have any feedback after integrating? Get in touch with us and tell us what you think in our forum, support@stytch.com, or in our Slack community.

Embed magic links into your existing user communications to seamlessly log in your users directly from their email or SMS inbox, and guide them back to an authenticated experience.

With our out-of-the-box email magic links product, Stytch is able to fully handle the frustrating and complex pieces of email deliverability, latency, and inbox placement. However, we also offer a flexible way for you to embed magic links into any use case you can imagine. For example, you could send magic links from your own domain, embed them into customized templates, or leverage different communication channels, like sms, to send them. By using our magic link create endpoint, you can embed magic links into all of your end-user communications to reduce friction and improve conversion. If needed, you can always add more authentication requirements to a user’s session to improve security by using the rest of Stytch’s product suite.

1. Step 1: Create magic link token

   Use the magicLinkCreate endpoint to generate a token for a user to embed in your chosen communication (e.g. a promotional email).

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   	    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"
   	}'

2. Step 2: Send token

   Send your customer communication with the magic link embedded in your main call-to-action button (you'll append the magic link token to the destination URL you're sending the user to).

3. Step 3: Authenticate token

   When the user clicks the link, redirect the user and send a request to Stytch's authenticate endpoint in order to verify the user. You can optionally set a session for the user by using the session_duration_minutes in the authenticate call.

   curl --request POST \
   	--url https://test.stytch.com/v1/magic_links/authenticate \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   	  "token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4="
   	}'

4. Step 4: Multi-factor authentication

   After this step, it's up to you on how you want to handle the user interaction. Depending on the use case, you may not need additional authentication. However, if you want to layer on step-up authentication at any point throughout the user’s session for additional assurance, you can always layer on more verification methods (e.g. SMS, etc.).

   curl --request POST \
   	--url https://test.stytch.com/v1/otps/sms/send \
   	-u 'PROJECT_ID:SECRET' \
   	-H 'Content-Type: application/json' \
   	-d '{
   	    "phone_number": "+12025550162"
   	}'