To begin using the AuthAlert API, first create a project and note down your unique project ID. This project ID is necessary for identifying your project in API calls. The API endpoint format is:

https://api.authalert.io/api/{projectId}


Replace {projectId} with your actual project ID in every API request.

Authentication Methods

There are two ways to authenticate your API calls:

• Domain Authentication (Recommended for Web Applications): Add the domain names that will access the API to your authorized domain list in the settings. This allows your web applications to make API requests.
• Token Authentication (For Non-Web Use): Use token-based authentication for mobile apps or other non-web platforms.

API Request Format

When making an API request, the input data should be in JSON format. Here’s an example:

{
 "email": "user@mysite.com",
 "device_id": "12kjfsui346",
 "user_id": "uirewe324ryuf",
 "first_name": "Josh",
 "last_name": "Smith"
}


Example cURL Request

Below is an example of how to call the API using cURL with token authentication:

curl -X POST <https://api.authalert.io/api/{projectId}> \\\\
-H "Authorization: Bearer your_token_here" \\\\
-H "Content-Type: application/json" \\\\
-d '{
 "email": "user@mysite.com",
 "device_id": "12kjfsui346",
 "user_id": "uirewe324ryuf",
 "first_name": "Josh",
 "last_name": "Smith"
}'


Using the AuthAlert npm Package

For web applications built with JavaScript frameworks like React, Angular, or Vue, we recommend using the AuthAlert npm package to simplify integration. Please note that the npm package supports domain authentication only.

Installation

To install the npm package, run the following command:

npm install authalert


Example Usage (Async/Await)

The npm package supports both async functions and promise chains. Here’s an example using async/await:

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);


Example Usage (Promise Chain)

Alternatively, you can use a promise chain:

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

The AuthAlertAPI function accepts the following input parameters:

• user_id
  • Example: "ac5c7322"
  • Description: Unique identifier for the user.
  • Required: Yes
• email
  • Example: john.smith@test.com
  • Description: The user's email address, needed for alert emails.
  • Required: Yes for Mailgun integration only
• first_name
  • Example: "John"
  • Description: The user's first name, used in alert emails.
  • Required: No
• last_name
  • Example: "Smith"
  • Description: The user's last name, used in alert emails.
  • Required: No

API Response

Upon a successful API call, the response will be a JSON object containing two boolean properties: new_user and new_device.

• new_user
  • If true, it indicates that the user_id is new to the AuthAlert system, and the system will register the user. In this case, new_device will always be true.
• new_device
  • If true but new_user is false, this indicates a new device has been detected for an existing user. If you have Mailgun or webhook integration enabled, alerts will be triggered.

If new_device is true, it is recommended that the frontend application triggers Multi-Factor Authentication (MFA) to enhance security by authorizing the new device. This approach improves security without requiring MFA on every authentication attempt, effectively implementing an "authorize this device" feature.

‍