Skip to main content

​
Portal setup

  1. Navigate to Authenticators in the Authsignal Portal, find email magic link, and click Set up.
  2. Choose an email provider. You can choose Authsignal for development but it’s recommended to use an alternative provider in production for more control over templates and delivery.

​
SDK setup

​
Server SDK

Initialize the SDK using your secret key from the API keys page and the API URL for your region. 
import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({
  apiSecretKey: "YOUR_SECRET_KEY",
  apiUrl: "YOUR_API_URL",
});

​
Web SDK

Initialize the Web SDK using your tenant ID from the API keys page and your API URL. 
import { Authsignal } from "@authsignal/browser";

const authsignal = new Authsignal({
  tenantId: "YOUR_TENANT_ID",
  baseUrl: "YOUR_API_URL",
});

​
Adaptive MFA

The following steps demonstrate how to implement adaptive MFA with email magic link - either at sign-in or as step-up authentication when the user performs a sensitive action in your app (e.g. making a payment).

​
1. Track action

Use a Server SDK to track an action in your backend. This step can apply rules to determine if a challenge is required.
  • Custom UI
  • Pre-built UI
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  attributes: {
    email: "jane.smith@authsignal.com",
  },
};

const response = await authsignal.track(request);

if (response.state === "CHALLENGE_REQUIRED") {
  // Return token to your frontend to present challenge
  const token = response.token;
}
You can choose a value for the action here which best describes what the user is doing in your app (e.g. signIn or createPayment). Each action can have its own set of rules. To learn more about using rules and handling different action states refer to our documentation on actions and rules.

​
2. Present challenge

If the action state is CHALLENGE_REQUIRED then you can present an email magic link challenge using the Web SDK.
  • Custom UI
  • Pre-built UI
// Set token from the track response
authsignal.setToken("eyJhbGciOiJ...");

// Send the user an email magic link
// You can call this multiple times via a 'resend' button
await authsignal.emailML.challenge();

// Check verification status
// This will resolve when user clicks the magic link
const verifyResponse = await authsignal.emailML.checkVerificationStatus();

if (verifyResponse.data?.isVerified) {
  // Obtain a new token
  const token = verifyResponse.data.token;
}

​
3. Validate action

Use the new token obtained from the client SDK to validate the action on your backend. 
const response = await authsignal.validateChallenge({
  action: "signIn",
  token: "eyJhbGciOiJIUzI....",
});

if (response.state === "CHALLENGE_SUCCEEDED") {
  // User completed challenge successfully
}
If the action state shows that the email magic link challenge was completed successfully, you can let the user proceed with the action.

​
Next steps

  • Adaptive MFA - Set up smart rules to trigger authentication based on risk
  • Passkeys - Offer the most secure and user-friendly passwordless authentication
⌘I