JavaScript SDK - Email magic links | Stytch B2B authentication

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

The SDK provides methods that can be used to send magic links and authenticate tokens in the links later.

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

Login or signup

The Login or signup method wraps the login or signup Email Magic Link API endpoint.

Method parameters

organization_id* string

email_address* string

login_redirect_url string

signup_redirect_url string

login_template_id string

signup_template_id string

locale string

import { useStytchB2BClient } from '@stytch/react/b2b';

export const Login = () => {
  const stytch = useStytchB2BClient();

  const sendEmailMagicLink = () => {
    stytch.magicLinks.email.loginOrSignup({
      email_address: 'sandbox@stytch.com',
      organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
    });
  };

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

RESPONSE

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

Invite

The invite method wraps the invite Email Magic Link API endpoint. The organization_id will be automatically inferred from the logged-in Member's session.

This method is not available for unauthenticated end users. In order to call this method, there must be a valid Member Session containing the necessary Role to complete this action. This method requires the Member to have permission to perform the create action on the stytch.member Resource.

In addition, Member actions & permissions must be enabled in the SDK Configuration page of the Stytch dashboard. To learn more about our RBAC implementation, see our RBAC guide.

Method parameters

email_address* string

invite_redirect_url string

invite_template_id string

name string

untrusted_metadata object

locale string

import { useStytchB2BClient } from '@stytch/react/b2b';

export const InviteMember = () => {
  const stytch = useStytchB2BClient();

  const inviteMember = () => {
    stytch.magicLinks.email.invite({
      email_address: 'sandbox@stytch.com',
    });
  };

  return <button onClick={inviteMember}>Invite a Member</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member": {...},
    "organization": {...}
  }

Authenticate

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

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the new factor to the existing Member Session.

If there is an intermediate session token, the SDK will call the endpoint with it. If the resulting set of factors satisfies the organization's primary authentication requirements and MFA requirements, the intermediate session token will be consumed and converted to a Member Session. If not, the same intermediate session token will be returned.

If this method succeeds and the Member is not required to complete MFA, the Member will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

If this method succeeds and MFA is required, the intermediate session token will be stored in the browser as a cookie.

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

Method parameters

magic_links_token* string

session_duration_minutes* int

locale string

import React, { useEffect } from 'react';
import { useStytchB2BClient, useStytchMemberSession } from '@stytch/react/b2b';

export const Authenticate = () => {
  const stytch = useStytchB2BClient();
  const { member_session } = useStytchMemberSession();

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

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

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "method_id": "member-email-test-1dd089b3-8904-47ef-b943-987968e549d4",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "reset_sessions": false,
    "session_jwt": "example_jwt",
    "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
    "intermediate_session_token": "",
    "member_authenticated": true,
    "mfa_required": null,
    "member_session": {...},
    "member": {...},
    "organization": {...}
  }

Send discovery email

The Send Discovery Email method wraps the send discovery email API endpoint.

Method parameters

email_address* string

discovery_redirect_url string

login_template_id string

locale string

import { useStytchB2BClient } from '@stytch/react/b2b';

export const Login = () => {
  const stytch = useStytchB2BClient();

  const sendDiscoveryEmail = () => {
    stytch.magicLinks.email.discovery.send({
      email_address: 'sandbox@stytch.com',
    });
  };

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

RESPONSE

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

Authenticate discovery magic link

The Authenticate Discovery Magic Link method wraps the authenticate discovery magic link API endpoint, which validates the discovery magic link token passed in. If this method succeeds, the intermediate session token will be stored in the browser as a cookie.

Method parameters

discovery_magic_links_token* string

import React, { useEffect } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const DiscoveryAuthenticate = () => {
  const stytch = useStytchB2BClient();

  const authenticate = async () => {
    const token = new URLSearchParams(window.location.search).get('token');
    const { intermediate_session_token, email_address, discovered_organizations } =
      await stytch.magicLinks.discovery.authenticate({
        discovery_magic_links_token: token,
      });
    console.log({ intermediate_session_token, email_address, discovered_organizations });
  };

  useEffect(() => {
    authenticate();
  });

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

RESPONSE

{
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "status_code": 200,
    "intermediate_session_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
    "email_address": "sandbox@stytch.com",
    "discovered_organizations": [{...}, {...}]
  }