Authsignal’s rules engine transforms static authentication flows into intelligent, risk-based security systems. Rules determine when and how to challenge users based on contextual factors.

Rules are conditional statements that evaluate the context of each action to make intelligent security decisions. While actions define what users are doing, rules determine when and how to challenge them based on risk factors, device characteristics, user behavior, and custom business data.

​
Creating a rule

To create a rule, navigate to your action (e.g., withdraw-funds) and click the Rules tab. Then click “Create rule” and provide a name and description.

​
Core components of a rule

When you create a rule in Authsignal, you’re defining the logic that determines when additional security measures are required. Here’s what a rule contains:

​
1. Conditions

Define the criteria that will trigger the rule using various data points, for example:

  • Device characteristics: New devices, device count
  • IP/Network data: Anonymous IPs, country codes, impossible travel detection
  • Custom data points: Your business-specific data like transaction amounts, account tiers

​
2. Outcomes

When a rule’s conditions are met, it can override the action’s default outcome with any of the four available action outcomes (ALLOW, CHALLENGE, REVIEW, or BLOCK). This allows you to apply outcomes dynamically based on risk assessment rather than using a static default.

​
Using rules with actions

Rules work seamlessly with your existing action tracking. When you track an action, Authsignal evaluates all applicable rules and returns the appropriate outcome.

// Track an action - rules are evaluated automatically
const result = await authsignal.track({
  userId: "0272c312-e181-4cad-a494-43647b503a0a",
  action: "withdraw-funds",
  attributes: {
    deviceId: "device-abc",
    ipAddress: "203.0.113.1",
    userAgent: "Mozilla/5.0..."
  }
});

// Handle the result based on rule evaluation
if (result.state === "CHALLENGE_REQUIRED") {
  // Rule determined a challenge is needed
  return {
    token: result.token // For custom UI with SDKs
  };
} else if (result.state === "ALLOW") {
  // Rule determined user is trusted
  return { success: true };
} else if (result.state === "REVIEW") {
  // Rule determined manual review is needed
  return { 
    status: "under_review",
    message: "Your request is being reviewed"
  };
} else if (result.state === "BLOCK") {
  // Rule determined this is high-risk
  return { 
    error: "This action has been blocked for security reasons"
  };
}

​
Creating a rule to challenge high-risk users

Let’s walk through creating a practical rule that automatically challenges high-risk users while allowing trusted users to access your application seamlessly.

​
1. Create a rule

  • Navigate to your signIn action and click the Rules tab
  • Click Create rule and name it Challenge “high-risk” users
  • Click Continue to proceed to rule configuration

​
2. Add conditions

We’ll determine a user as ‘high-risk’ if they meet any of the following conditions:

  • Are detected as being a bot
  • Are on a new device
  • Are using an anonymous IP address

To add these conditions:

  • Click Add feature and then Select feature
  • Choose the Device category and select Device is new
  • Repeat for Device is a bot (Device category)
  • Repeat for IP is anonymous (IP/Network category)
  • Change the conjunction logic from AND to OR so the rule triggers if any condition is met

​
3. Set the outcome

  • Set the rule outcome to CHALLENGE so high-risk users will be prompted for additional verification, then click Save.
  • Return to the Rules page of your signIn action. You should see your new rule listed.

​
4. Configure default action outcome

  • Navigate to your action’s Settings tab
  • Change the default outcome to ALLOW
  • Click Save

This ensures users who don’t trigger the high-risk rule can proceed without challenge.

​
5. Update your track call

Now that you have created the rule, you’ll need to update your track action call to include some additional fields: deviceId, ipAddress, and userAgent.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  attributes: {
    deviceId: "<device-id>", // From __as_aid cookie if using Authsignal Web SDK
    userAgent: "<user-agent>",
    ipAddress: "<ip-address>"
  }
};

const response = await authsignal.track(request);

// Handle the response
if (response.state === "CHALLENGE_REQUIRED") {
  // Use token with client SDK
  return { token: response.token };
} else if (response.state === "ALLOW") {
  // User is trusted, proceed
  return { success: true };
}

Note: When using the Authsignal Web SDK, you can obtain the deviceId from the __as_aid cookie that’s automatically created on the client side.