Welcome to AuthAlert, your trusted partner in authentication security. We specialize in providing cutting-edge solutions to safeguard your users' digital identities and protect their sensitive information. With AuthAlert, you can ensure that your users' online accounts are securely fortified against unauthorized access and potential breaches.

Features

AuthAlert offers a comprehensive suite of features designed to enhance security and build trust:

• Device Detection: Instantly identifies new devices accessing user accounts.
• Multi-Factor Authentication (MFA): Triggers MFA exclusively for new devices, adding an extra layer of security.
• Alert Notifications: Sends alerts to users via API, email through Mailgun, or webhooks to keep them informed.
• Webhook Automation: Integrates seamlessly with your systems to automate processes when new devices are detected.
• Ease of Use: Simple to implement and scalable to meet your growing needs.

This package is optimized for JavaScript frontends, including frameworks such as React, Vue.js, and Angular.

Installation

Installing AuthAlert is straightforward. Run the following command in your project directory:

npm install authalert


Using the API

The AuthAlert API is flexible and can be utilized either as a Promise or within an asynchronous function.

Async Function Example

Here's how to use the API within an asynchronous function:

import AuthAlertAPI from 'authalert';

const projectId = "your_project_ID";

const result = await AuthAlertAPI(projectId, {
 user_id: user.id,
 email: user.email,
 first_name: user.first_name,
 last_name: user.last_name
});

console.log(result);


Promise Example

Alternatively, you can use the API with Promises:

import AuthAlertAPI from 'authalert';

const projectId = "your_project_ID";

AuthAlertAPI(projectId, {
 user_id: user.id,
 email: user.email,
 first_name: user.first_name,
 last_name: user.last_name
})
 .then(res => {
   console.log(res);
 })
 .catch(err => {
   console.error(err);
 });


Input Variables

When using the API, you need to provide specific user data:

• user_id: A unique identifier for the user (e.g., "ac5c7322"). This is required.
• email: The user's email address (e.g., "john.smith@test.com"). This is required only if you are integrating with Mailgun.
• first_name: The user's first name (e.g., "John"). This is optional.
• last_name: The user's last name (e.g., "Smith"). This is optional.

To obtain your project_ID, visit the AuthAlert website and create a project.

Authentication

To securely use the AuthAlert API in your frontend applications, you must authorize your domains:

• Web Applications: Add your website or web app domain names to the authorized domain list. Unauthorized API requests will result in 403 errors. Manage your authorized domains through the AuthAlert platform.
• Mobile Applications: Utilize token authorization by setting the token on your project's settings page.

API Response

Upon a successful API call, AuthAlert evaluates whether the user is new to the system and if the device is new to the user. The response will be in the following format:

{
 "new_user": false,
 "new_device": true
}


If "new_device" is true, redirect users to the MFA route. This ensures that MFA is triggered only for new devices. Additionally, you can implement a "remember me" feature to allow users to bypass MFA on specific trusted devices.

Mailgun Integration

Integrating Mailgun with AuthAlert enables you to send email alerts automatically when new devices are detected, without any additional coding. To set up Mailgun integration:

1. Activate Integration: Toggle the Mailgun option in your AuthAlert project settings.
2. Configure Settings: Enter your Mailgun domain, API key, sender email, subject line, and template name.
3. Create Template: In your Mailgun account, create an email template using the following variables:
   • first_name: The user's first name (e.g., "John").
   • last_name: The user's last name (e.g., "Smith").
   • new_device_os: The operating system of the new device (e.g., "Mac OS X").
   • new_device_os_version: The OS version of the new device (e.g., "10").
   • new_device_browser: The browser used on the new device (e.g., "Firefox").
   • new_device_browser_version: The browser version (e.g., "128").
   • new_device_device_brand: The brand of the new device (e.g., "Apple").
   • new_device_country: The country code where the new device is located (e.g., "AU").
   • new_device_region: The state or province of the new device's location (e.g., "NSW").
   • new_device_city: The city or metro area of the new device (e.g., "Sydney").
   • new_device_detection_time: The timestamp when the device was first detected (e.g., "2021-08-31 17:32:38 AEST").

Webhook Integration

Webhook integration allows for programmatic interactions, enabling you to connect AuthAlert with CRM systems or other communication channels beyond Mailgun. To set up webhook integration:

1. Activate Integration: Toggle the webhook option in your AuthAlert project settings.
2. Configure Settings: Enter the webhook URL and a secret key for secure communication.

When a new device is detected, AuthAlert sends a JSON payload to your specified webhook URL containing detailed information about the user and the device. Here is an example of the payload:

{
 "user_id": "HZkj3L8we0gZjnHlrxziA53e1TH2",
 "email": "",
 "first_name": "",
 "last_name": "",
 "device_id": "6uex31zf1tx",
 "subscription_id": "q9enh4fcvjmPDDVR1mNT",
 "new_device": {
   "device_id": "6uex31zf1tx",
   "os": "Mac OS X",
   "os_version": "10",
   "browser": "Firefox",
   "browser_version": "128",
   "device_brand": "Apple",
   "device_model": "Mac",
   "device_family": "Mac",
   "country": "AU",
   "region": "NSW",
   "city": "Sydney",
   "city_lat_long": "-33.868820,151.209295",
   "detection_time": 1615819845,
   "timezone": "sydney/australia"
 }
}



This payload provides comprehensive details about the user and the new device, allowing you to effectively automate and customize your security responses.

‍