Account Takeover Detection User Guide
Account Takeover Detection Overview
Introduction
Fraudsters are increasingly using social engineering and techniques such as SIM Swap and SIM jacking to take over phone numbers belonging to legitimate customers. When successful this enables fraudsters to intercept SMS and other mobile channels, enabling them to access One Time PIN codes and other messages sent to customers.
Enterprises can protect themselves and their customers by using Account Takeover Detection and other Syniverse services such as Multi-Factor Authentication, Phone Number Verification and Right Party Verification.
Service Overview
Account Takeover Detection enables Enterprises to reduce fraud and increase security when communicating with their customers. Common scenarios where Enterprises use ATO Detection are when authenticating end users using a SMS One Time PIN code, or sending fraud alerts via SMS.
It also protects other channels / methods that use a mobile number, such as voice, WhatsApp and Rich Communication Services
The ATO Detection API is a REST-like server-to-server API and requires Enterprises to host the end-user-facing user interface and obtain end-user consent.
Enterprises call this API to find out if an end-user’s mobile channel may be compromised before deciding to either let the end-user continue in the regular flow or to step up authentication using another channel (e.g. knowledge or inherence factors). This is made possible by Syniverse analyzing phone signals around the end-user’s SIM and giving the Enterprise an indicator whether the mobile channel has any recent changes that violate a Enterprise’s pre-defined risk tolerance.
|
API Call |
Function |
|
simCheck |
This API call is used to determine if the mobile channel of an end-user has had recent SIM changes (or call forwarding enabled) indicating possible risk of an account takeover. |
Integration
Security and Encryption
Since Syniverse’s Mobile Identity platform handles sensitive end-user information, utmost care is taken to safeguard this information at all times. Syniverse implements multiple layers of security between the Enterprise system and Syniverse’s system.
1. Secure Communication Channel: All communication between the Enterprise’s system and Syniverse’s system takes place over HTTPS (TLS version 1.2 or above).
2. IP Address Whitelisting: Enterprise system’s IP addresses are whitelisted before any API calls can be made to Syniverse’s production environment.
3. API Request Validation: Enterprise is assigned a Merchant ID, an optional submerchant ID and an API Secret. The Secret is an alphanumeric string and is shared with the Enterprise during the onboarding process. Enterprise must send the API Secret in the header for all API requests. Syniverse processes the request only if it comes with a valid API Secret. Please contact Syniverse’s Support team to know the validity of the API Secret – the Support team will issue a new one prior to the expiry of the current value.
Security Credentials
The following lists all possible credentials provided by Syniverse to ensure authentication of APIs, security and privacy of the end-user information.
|
API Call |
Security Values |
Utilization |
Key Length |
|
simCheck
|
API Secret |
Key to use in the request header (Authorization) of all APIs. Shared with Enterprise at onboarding. |
Up to 128 characters |
Constructing Requests
Syniverse exposes easy-to-use REST-like APIs and requests should be sent as JSON objects. Enterprises can use standard libraries to create the requests. Below table shows the request header details .
Request header details
| Parameter | Description | Required |
| Accept |
Media type for the response. Only application/json is supported. Example Accept: application/json |
Yes |
| Content-Type |
Media type sent in the request. Only application/json is supported. Example Content-Type: application/json |
Yes |
| Authorization |
The security key to use for Syniverse APIs, which was shared during the onboarding process. Example Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG |
Yes |
| RequestTime |
Current date time when request is sent. Request time in ISO 8601 format: YYYY-MM-DDThh:mm:ss.ffffff Example RequestTime: 2017-03-21T19:28:53+09:00 |
Yes |
Processing Response
The Syniverse Mobile Identity platform returns response values as JSON objects. Enterprises should use a JSON parser to extract the information. Below table shows Response header details.
Response header details
|
Parameter |
Description |
|
Content-Type |
Media type sent in the response. Example Content-Type: application/json |
Sandbox
During integration the Enterprise will use the Mobile Identity sandbox to develop and test against. The sandbox provides dummy data to simplify testing of different scenarios and test cases.
Access details & credentials for the sandbox will be provided by Syniverse during onboarding.
Service Configuration
Syniverse's Account Takeover Detect works by returning a Y/N indicator to a timestamp challenge. Enterprise determines that they want to know if there has been a Account Takeover or SIM change within a pre-defined timeframe, for example the last 48 hours (SIM change is defined as a new association between a MSISDN and an IMSI or SIM Identifier). Syniverse will return a Yes (Y) or No (N) response if a SIM change has taken place based on the time of the request.
Additionally, if the Enterprise plans to use voice OTP (One Time Passcode) as a method to verify device possession by an end-user, then Syniverse will also look into whether call forwarding is enabled for the end-user’s phone number. The API response will still return only one Y/N response to notify the Enterprise if the end-user’s mobile channel has seen one either a SIM change or call forwarding enabled, indicating a possible risk for the Enterprise if they continue to authenticate using this channel.
If data (SIM change and call forwarding if configured) is not available for an end-user’s phone number, then Syniverse will return an error code -5061(please refer to Appendix A) instead of Y/N.
During implementation Syniverse will configure your account accordingly to set a pre-defined risk-tolerance timeframe in hours and enable inclusion of detecting call forwarding. Enterprises may have a range as short as 1 hour or a longer range of 14 days for example. If a range of 14 days is preferred by a Enterprise, then Syniverse would configure the Enterprise’s API with a Account Takeover range in the corresponding number of hours i.e., 336 hours. SIM change, call forwarding availability, and consent requirements may vary per carrier.
The production URL will also be confirmed by Syniverse as part of the implementation. This is because there are different geographic deployments used depending on the country.
API Specification
Account Takeover Detection
Request URL
https://Syniverseserverurl/cigw/v1/simCheck
The actual URL will be provided during onboarding.
Request parameter details
|
Parameter |
Description
|
Required |
|
|
merchantId |
A unique string assigned by Syniverse to identify the Enterprise. This ID will be provided by Syniverse during the onboarding process. Max length: 30 Example merchantId: 00DF00000015 |
Yes |
|
|
subMerchantId |
Resellers Only This unique ID is assigned to a reseller’s end Enterprise. This ID will be provided by Syniverse during the onboarding process. Max length: 30 Example subMerchantId: 00DF00000016 |
No |
|
|
consentId |
Enterprise passes a unique ID from capturing the consent from the end-user. It needs to be traceable back to the channel how the end-user had provided the consent. If Consent ID is not passed, only fields that are available without consent will be returned in the response. Max length: 128 Example consentId: uyciydfoudqwg912863017 |
Yes |
|
|
consentTimeStamp |
Date and time when end-user consent was obtained. Format: yyyy-MM-ddTHH:mm:ss +00:00 Example consentTimeStamp: 2021-02-03T20:20:39+00:00 If Consent TimeStamp is not passed, only fields that are available without consent will be returned in the response. |
Yes |
|
|
msisdn |
The end-user’s mobile number in E.164 international format. Example msisdn: +14444441111 |
Yes |
|
|
correlationId |
Enterprise’s transaction identifier that can uniquely identify this particular transaction. Min length: 8, Max length: 80 Example correlationId: 1310881973286793 |
Yes |
|
Response parameter details, if API call is successful
|
Parameter |
Description |
|
results |
This JSON object encapsulates the API response. This object includes the elements listed below (each element is defined in the table below the sample). { "simChangeDate": "2021-02-03T00:00:00Z", “callForwardingEnabled”: “10”, “changeDetected”: “Y”, "correlationId": "1310881973286793", "responseId": " 20210203234640M163C264030"
}
|
Results object details
|
Parameter |
Description |
|
correlationId |
Enterprise’s transaction identifier that can uniquely identify this particular transaction. Min length: 8, Max length: 80 Example correlationId: 1310881973286793 |
|
responseId |
Syniverse’s unique transaction reference identifier. Max length: 30 Example responseId: 20200325234640M163C264030 |
|
changeDetected* |
The indicator that tells the Enterprise if Syniverse saw a change event (and/or call forwarding enabled, if configured for Enterprise) in the mobile channel for the end-user during the preconfigured SIM change range. * Max Length: 5 Example changeDetected: Y |
|
simChangeDate** |
If available from a carrier and if sharing is permitted, the exact date and/or timestamp when the last MSISDN-to-SIM pairing changed took place. Example simChangeDate: 2020-08-15T19:20:30+00:00 |
|
callForwardingEnabled** |
If available from a carrier and if sharing is permitted, this indicates if call forwarding has been set-up by the subscriber for the phone number. 10 indicates true and 0 indicates false. Example callForwardingEnabled: 10 |
*changeDetected definitions:
Y: Yes, the mobile channel for the end-user has seen a change event or call forwarding enabled and Syniverse recommends the Enterprise should step up authentication for this end-user (e.g. either knowledge or inherence factors).
N: No, the mobile channel for the end-user has not seen a change event or call forwarding enabled and Syniverse recommends the Enterprise to allow the end-user to continue in the flow without added friction.
** simChangeDate, callForwardingEnabled:
These two fields are only available if a carrier is providing the information and sharing is permitted.
Response parameter details, if API call is not successful
|
Parameter |
Description |
|
error |
This is the object that encapsulates the API response. Included in place of the results object if the call is not successful |
|
correlationId |
Enterprise’s transaction identifier that can uniquely identify this particular transaction, if available. The value from the request is echoed back. Min length: 8, Max length: 80 Example correlationId: ABC0881973286793 |
|
responseId |
Syniverse’s transaction identifier than can uniquely identify this particular transaction, if available. Max length: 30 Example responseId: 20200325234640M163C264030 |
|
code |
Indicates the reason the call failed. Example code: -5001 |
|
description |
Additional information regarding the error condition. Set only if error code is included in the response. Max Length: 256 Example description: Authentication failed |
Example request
POST https://serverurl/cigw/v1/simCheck
Accept: application/json
Content-Type: application/json
Authorization: qPrOHV9HuUaicXrK9I9hM5pmR2QG
RequestTime: 2021-02-04T19:28:53+00:00
{
"merchantId":"00DF00000015",
"subMerchantId":"00DF00000016",
"consentId":"uyciydfoudqwg912863017",
"consentTimeStamp":"2021-02-03T12:30:23+00:00",
"correlationId":"ABC0881973286793",
"msisdn":"+13333330001"
}
Example successful response
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": {
"simChangeDate": "2021-02-03T00:00:00Z ",
"callForwardingEnabled": "10",
"changeDetected": "Y",
"correlationId": "ABC0881973286793",
"responseId": " 20210203234640M163C264030"
}
}
Example error response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": {
"correlationId":"ABC0881973286793",
"responseId":" 20210203234640M163C264030",
"code":"-5061",
"description":"Insufficient information to determine response"
}
}
Appendix A – Error Codes and Descriptions (Error Object)
|
Error Code |
Error Description |
Comments |
Recommended Action |
|
-5000 |
Access not allowed. |
Access not allowed for the requested API. |
Integration Issue. Contact Syniverse Support for help. |
|
-5001 |
Authentication failed. |
Enterprise authentication failed. Check the signature computation. |
Integration Issue. Contact Syniverse Support for help. |
|
-5002 |
Unsupported version. |
Unsupported version used for the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5003 |
Retry with missing parameter. |
A required parameter is missing from the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5004 |
An invalid parameter was passed. |
An invalid parameter was passed in the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5005 |
An internal error occurred. |
An internal error has occurred. |
Retry. If error persists, Contact Syniverse. |
|
-5006 |
Retry with end-user identifier. |
An end-user identifier such as the mobile number, authentication key or association key is missing from the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5009 |
This phone number is not whitelisted. |
Whitelisting is enabled and the phone number is not whitelisted. |
Contact Syniverse Support to whitelist number. |
|
-5010 |
Missing or Incorrect Submerchant Id. |
A valid sub-merchant id is required for reseller Enterprises. |
Integration Issue. Contact Syniverse Support for help. |
|
-5013 |
Exceeded time to perform end-user identification. |
The authentication key has expired before end-user identification could be completed. |
Do not retry. Terminate transaction and exit. |
|
-5017 |
Retry with passing consent in the input. |
User consent is needed to make this API call in the current configuration. |
Integration Issue. Contact Syniverse Support for help. |
|
-5018 |
Please retry with both consentId and consentTimeStamp |
Either consent id or consent timestamp was missing from the API request. |
Integration Issue. Contact Syniverse Support for help. |
|
-5020 |
Data is not available for this user |
Data is not available for this user from any of the configured data sources. |
Do not retry. Terminate transaction and exit. |
|
-5022 |
Invalid Enterprise. |
The Enterprise cannot be recognized. |
Integration Issue. Contact Syniverse Support for help. |
|
-5029 |
Data access not allowed. Please contact Customer Support. |
The Enterprise is not configured for this API or for the Attribute Groups being requested. |
Integration Issue. Contact Syniverse Support for help. |
|
-5030 |
Data access not allowed. Please contact Customer Support. |
Service providers are not configured for this Enterprise. |
Integration Issue. Contact Syniverse Support for help. |
|
-5033 |
Consumer identifier is invalid. |
The end-user identifier such as the mobile number, authentication key or association key is invalid. |
Do not retry. Terminate transaction and exit. |
|
-5035 |
This Authentication Key has expired. |
The authentication key has expired and cannot be used anymore. |
Do not retry. Terminate transaction and exit. |
|
-5037 |
Service provider error occurred. Please retry. |
An error occurred while communicating with a service provider. |
Retry. If error persists, Contact Syniverse Support. |
|
-5046 |
No value was passed for consumerMdn and carrier. |
No value was passed for consumerMdn and carrier. |
Please retry by passing both the values. |
|
-5049 |
No value was passed for consumerMdn or carrier. |
No value was passed for consumerMdn or carrier. |
Please retry by passing either of the values. |
|
-5050 |
Data access not allowed. Please contact Enterprise Support. |
Data access not allowed. Please contact Enterprise Support. |
Integration Issue. Contact Syniverse Support for help. |
|
-5053 |
Please retry with a valid MSISDN |
Please retry with a valid MSISDN |
Retry. If error persists, Contact Syniverse Support. |
|
-5054 |
Please retry with valid Consent |
Input consent parameters are not valid. |
Retry. If error persists, Contact Syniverse Support. |
|
-5055 |
Consent is no longer active |
Consent is no longer active. |
Please obtain new consent from the user and retry |
|
-5056 |
Please retry with valid Consent |
Consent is no longer active. |
Please obtain new consent from the user and retry |
|
-5057 |
Carrier not supported. |
Syniverse has not integrated with the carrier and there is no access to other authoritative data sources for the MSISDN |
Do not retry. Terminate transaction and exit. |
|
-5061 |
Insufficient information to determine response |
Syniverse did not obtain sufficient information from mobile carrier to determine a response. |
Do not retry. Terminate transaction and exit. |
|
-5062 |
Unable to identify carrier |
Syniverse could not identify the carrier associated with the phone number. nxx are two digits used for internal tracking. |
Do not retry. Terminate transaction and exit. |