Skip to main content

​
Email provider setup

Navigate to Authenticators in the Authsignal Portal, click on Email magic link, and choose an email provider.
  1. Log in to your Bird account
  2. Get your Access key and Workspace ID from your Bird settings
  3. Create or locate an email channel and note the Channel ID
  4. Create an email template in Bird and note the Project ID/Template ID
  5. Publish your template and note the Published version ID
  6. In the Authsignal Portal, select Bird as your email provider
  7. Enter your Bird access key, workspace ID, channel ID, project ID/template ID, published version ID, and select your default language

​
Email template variables

The following template variables are available for use in your email template:
​
url
string
The magic link URL.
​
actionCode
string
The action that the user is performing.
​
userId
string
The ID of the user.
​
userAgent
string
The user agent associated with the action.
​
ipAddress
string
The IP address associated with the action.

​
Custom template variables

You can forward custom data points to your email provider as additional template variables. This is useful for personalizing emails with data specific to your application, such as a user’s account ID or a transaction amount. To configure this, navigate to your email magic link settings in the Authsignal Portal and select which custom data points to include under Custom template variables. Custom data points are prefixed by model type:
  • User data points are prefixed with user_ (e.g. user_accountId)
  • Action data points are prefixed with action_ (e.g. action_transactionAmount)
Custom data points must be registered in the Authsignal Portal before they can be selected. Only registered data points with values set on the user or action will be included.

​
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. 
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") {
  // Obtain token 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. 
// 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