Email Magic Links

The JavaScript SDK provides a pre-built UI to trigger Email Magic Links, and methods to send and authenticate magic links that you can connect to your own UI. Use either of these approaches to quickly get up and running with magic links.

Methods

To call these methods, Email Magic Links must be enabled in the SDK Configuration page of the Stytch dashboard.

Send

The Send method wraps the send Email Magic Link API endpoint. This method requires that the user already exist within Stytch before a magic link may be sent. This method is useful for gating your login flow to only pre-created users, e.g. an invite or waitlist.

This method is also used when you need to add an email address to an existing Stytch User. If there is a currently valid Stytch session, and the user inputs an email address that does not match one on their Stytch User object, upon successful authentication the new email address will be appended to the emails array. Note, this does expose a potential account enumeration vector, see our article on preventing account enumeration for more details.

Method parameters

email* string
Configuration object

Additional configuration.

login_magic_link_url string
signup_magic_link_url string
login_expiration_minutes int
signup_expiration_minutes int
login_template_id string
signup_template_id string
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const sendEmailMagicLink = () => {
    stytchClient.magicLinks.email.send('sandbox@stytch.com', {
      login_magic_link_url: 'https://example.com/authenticate',
      login_expiration_minutes: 5,
    });
  };

  return <button onClick={sendEmailMagicLink}>Send email</button>;
};

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
  }

Login or create

The Login or create method wraps the login_or_create Email Magic Link API endpoint.

Method parameters

email* string
Configuration object

Additional configuration.

login_magic_link_url string
signup_magic_link_url string
login_expiration_minutes int
signup_expiration_minutes int
login_template_id string
signup_template_id string
import { useStytch } from '@stytch/react';

export const Login = () => {
  const stytchClient = useStytch();

  const sendEmailMagicLink = () => {
    stytchClient.magicLinks.email.loginOrCreate('sandbox@stytch.com', {
      login_magic_link_url: 'https://example.com/authenticate',
      login_expiration_minutes: 60,
      signup_magic_link_url: 'https://example.com/authenticate',
      signup_expiration_minutes: 60,
    });
  };

  return <button onClick={sendEmailMagicLink}>Send email</button>;
};

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
  }

Authenticate

The Authenticate method wraps the authenticate magic link API endpoint which validates the magic link token passed in.

If this method succeeds, the user will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchSession hook if you are using React.

Method parameters

token* string
Configuration* object

Additional configuration.

session_duration_minutes* int
import React, { useEffect } from 'react';
import { useStytch, useStytchSession } from '@stytch/react';

export const Authenticate = () => {
  const stytchClient = useStytch();
  const { session } = useStytchSession();

  useEffect(() => {
    if (session) {
      window.location.href = 'https://example.com/profile';
    } else {
      const token = new URLSearchParams(window.location.search).get('token');
      stytchClient.magicLinks.authenticate(token, {
        session_duration_minutes: 60,
      });
    }
  }, [stytchClient, session]);

  return <div>Loading</div>;
};

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
    "method_id": "email-test-81bf03a8-86e1-4d95-bd44-bb3495224953",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "session_jwt": "eyJ...",
    "session": {...},
  }

UI components

The SDK also comes with a pre-built UI component for our Email Magic Links product. It wraps our login_or_create Email Magic Link API endpoint, which finds an existing user or creates a new user and sends them a magic link via email.

To add Email Magic Links to the login UI, add SDKProductTypes.emailMagicLinks to the products array in the configuration and the appropriate emailMagicLinksOptions.

To see all authentication and customization options, see the UI config section below.

import React from 'react';
import { Products } from '@stytch/vanilla-js';
import { StytchLogin } from '@stytch/react';

const config = {
  emailMagicLinksOptions: {
    loginExpirationMinutes: 30,
    loginRedirectURL: 'https://example.com/authenticate',
    signupExpirationMinutes: 30,
    signupRedirectURL: 'https://example.com/authenticate',
  },
  products: [Products.emailMagicLinks],
};

export const Login = () => {
  return <StytchLogin config={config} />;
};