Login Protection
Overview
The Login API for is used at the time of customer login to prevent unauthorized users from accessing a user's account, conducting malicious activity at the time of login and gaining access to PII, payment data and other account related assets.
Primary Use Cases
There are a number of ways you can utilize the login protection offered by this API. The Login API can be used to enforce the following scenarios:
- Account take over (ATO): To prevent incidents where fraudsters use stolen credentials to try and gain access user accounts, to data theft, fraud, and brand damage.
- MFA Optimization: enhances multi-factor authentication (MFA) by reducing friction for legitimate users while strengthening security against fraud.
- Credential Stuffing & Bot Protection: safeguards accounts from automated attacks where fraudsters use stolen username-password pairs to gain unauthorized access. Credential stuffing exploits reused credentials from data breaches, while bots automate login attempts at scale.
- Extended Session: allows users to stay logged in for a longer period without needing to re-authenticate, improving convenience and user experience.
Integration Steps
In your dedicated Forter portal, you will receive a JavaScript snippet for both sandbox and production. For native mobile apps, you will receive links to download Forter's Native SDKs. You'll paste the JS script on the appropriate pages of your website or call mobile SDK methods on relevant mobile app screens so that it can load and asynchronously collect important behavioral data from your customer. The script or mobileUID generated by the mobile SDK will also generate a unique token for each user on your site that should be included in the Account Sign Up API Request Body.
Send login request for decision
Forter's Login API can provide a decision to approve a frictionless login or suggest that Multi-Factor Auth if suspicious activity is detected. Because of load considerations (bots) Forter typically asks to receive ONLY successfully authenticated traffic (password was correct) via the Login API.
Login API Request
Primary Data Points are:
- Account ID: Customer's account UID in merchant's site. Should not be the user email. If no account ID is available send NO_ACCOUNT_ID
- User Input: Input details submitted by the user. Required in case Forter does not have a full list of merchant account details (typically email)
- ConnectionInformation - Cyber intelligence data to analyze browsing behavior, device and connection quality such as IP address, user agent and data collected via JS / mobile SDK
- LoginMethodType (e.g. Password vs SMS) and status (indication of success) or AUTH_TOKEN_REFRESH in the case of refreshing an idle user session
- Details of AdvancedAuthenticationMethod is one was used by the merchant (e.g. MFA was already applied)
{
"accountId": "e520-ba9a-367-60b",
"eventTime": 1415287568000,
"connectionInformation": {
"customerIP": "10.0.0.127",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64)",
"forterTokenCookie": "2315688945984"
},
"loginMethodType": "PASSWORD",
"loginStatus": "SUCCESS",
"channelType": "WEB",
"userInput": {
"inputType": "EMAIL",
"email": "[email protected]"
}
}Login API Response
The response includes the Forter decision and potential recommendations, as well as a correlation ID that should be stored and used when the merchant provides additional updates (e.g. result of MFA if additional verification was recommended).
Key Fields:
- forterDecision: The latest Forter decision regarding the attempted action. Said fields may hold one of various options:
- "APPROVE" for approved signup requests, where user should be allowed to register for a new accounts;
- "DECLINE" for declined signup requests, where user should be declined from registering for new accounts;
- "VERIFICATION_REQUIRED" for signup requests, where user should be triggered an additional verification (via email, sms, etc.,;
- "NOT_REVIEWED".
- recommendation: A specific recommendation for an action that might help the customer to complete their transaction/action (e.g. verify phone via SMS, verify via push notification, verify email, perform a 3DS check, etc.)
- correlationId: A Forter unique identifier that should be sent to Forter as part of the AdvancedAuthenticationMethod object to correlate the MFA recommendation given in this response with the relevant additional authentication attempt result.
{
"forterDecision": "APPROVE",
"decisionReason": "",
"accountId": "e520-ba9a-367-60b",
"correlationId": "HGJ7512345H3DE",
"recommendation":""
}{
"forterDecision": "VERIFICATION_REQUIRED",
"decisionReason": "",
"accountId": "e520-ba9a-367-60b",
"correlationId": "HGJ7512345H3DE",
"recommendation": "EMAIL_VERIFICATION",
"verificationMethod":{
"verificationId": "88yr28r890u",
"correlationId": "e520-ba9a-367-60b",
"type": "OTP_EMAIL",
}
}Send request to extend user session
Forter's Login API can also be used to extend an idle user's session without requiring password multi-factor authentication for legitimate customers - resulting in a simplified and frictionless user account experience for legitimate customers. The Login API can return a binary approve/decline decision that allows you to determine whether a user requesting an extended session should be permitted from accessing the account in a frictionless manner, or should friction in the form of MFA, password be triggered for validation.
Login API Request Forter can provide a decision to approve a frictionless login or suggest that Multi-Factor Auth if suspicious activity is detected.
Because of load considerations (bots) Forter typically asks to receive ONLY successfully authenticated traffic (password was correct) via the Account Login API. For full details, please see the Login API section for more details.
Primary Data Points are:
- Account ID
- User Input (typically email)
- ConnectionInformation - Cyber intelligence data to analyze browsing behavior, device and connection quality such as IP address, user agent and data collected via JS / mobile SDK
- LoginMethodType parameter should be populated with AUTH_TOKEN_REFRESH in the case of refreshing an idle user session
- Details of AdvancedAuthenticationMethod is one was used by the merchant (e.g. MFA was already applied)
{
"accountId": "e520-ba9a-367-60b",
"eventTime": 1415287568000,
"connectionInformation": {
"customerIP": "10.0.0.127",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",
"forterTokenCookie": "2315688945984"
},
"loginMethodType": "AUTH_TOKEN_REFRESH",
"loginStatus": "SUCCESS",
"channelType": "WEB",
"userInput": {
"inputType": "EMAIL",
"email": "[email protected]"
}
}Login API Response The response includes the Forter decision and potential recommendations, as well as a correlation ID that should be stored and used when the merchant provides additional updates (e.g. result of MFA if additional verification was recommended).
{
"forterDecision": "APPROVE",
"decisionReason": "",
"accountId": "e520-ba9a-367-60b",
"correlationId": "HGJ7512345H3DE",
}Send authentication attempts
The Authentication result API is used to Inform Forter of authentication results after an MFA was required by a previous Login API request, using the provided correlation ID. While no decision is provided on this request, it is required in order to ensure optimal customer experience as well as continuously improving the decision model.
Authentication result API Request
Key Fields:
- accountId: Customer's account UID in merchant's site
- eventTime: The time that the trigger event occurred in MILLISECONDS
- additionalAuthenticationMethod.correlationId: A forter unique identifier that was provided as part of a Forter API response recommending additional authentication measures. Used to correlate between the user action which triggered the recommendation and the authentication attempt result. Required when the additional authentication was triggered by Forter's recommendation.
- additionalAuthenticationMethod.verificationOutcome: may take various forms depending on verification outcome. for example additionalAuthenticationMethod.verificationOutcome is a general authentication result enumerated field with 3 possible values: ["SUCCESS"; "FAILURE"; NONE_ATTEMPTED]
- Please see the Authentication result API Reference section for more details.
{
"accountId": "e520-ba9a-367-60b",
"eventTime": 1415287568000,
"connectionInformation": {
"customerIP": "10.0.0.127",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",
"forterTokenCookie": "2315688945984"
},
"channelType": "WEB",
"additionalAuthenticationMethod": {
"verificationOutcome": "SUCCESS",
"correlationId": "87363864834",
},
}Authentication Result API Response As this API is only used to provide Forter's model's additional information, the decision returned will always be "NOT_REVIEWED". Supplementary parameters like correlationId and accountId are also returned in the API response.
Prepare and Upload Historical Data
To ensure the highest level of accuracy for our decisioning model, Forter customizes our model to fit the specific risk profile of each of our customers. We achieve this by training the model with your past signup and login data in order to provide you with better accuracy from Day 1.
Complete Integration Tests
The purpose of Forter's integration tests is to make sure that your integration covers all relevant use cases, while still in the sandbox or test environment. Each use case may need a different combination of attributes and values.
To make sure you have covered each of the use cases we expect in your integration, please go through the test scenario list in the Integration Tests section of Portal. For each, you'll need to create the scenario in your sandbox site that will generate a call to Forter's API. Then, select the corresponding API request that Forter received and click Run to verify that the sample request meets the criteria.
Deploy to Production
Once the Integration tests have passed, and you've reviewed any gaps with a Forter Implementation Engineer please, deploy your code to your production environment, with two critical adjustments:
- Replace your Site ID and secret key with your production credentials.
- Update your Javascript snippet and Mobile SDKs to use your production Site ID and the production hash keys, if relevant.
Please note that this does not yet complete your integration. Until Forter has switched your site to Live (after Data Validation and Listen Mode), all Forter decisions will return "Not Reviewed".
Once in production, Forter uses a Data Validation tool to execute a set of automated tests across your live data in aggregation. The test outputs are daily reports that validate the accuracy and completeness of the production data we receive from you. You can monitor this output in Forter Portal under Integration Center Tools.
We recommend checking the report daily to identify any failed tests, which will prevent you from moving forward to Listen Mode.
In "listen mode", we will monitor the production traffic on your site and calibrate our models before we begin to provide you with decisions. This is a critical stage to ensure you meet your KPIs, and usually lasts around 7-14 days. Your Implementation Engineer will update you on the specific timeline for your integration.
During this time, Forter will continue to return "Not Reviewed" decisions in the API response.
Go Live
As Forter begins to send decisions and recommendations, confirm that your production site is handling responses as expected.