Login

To request a recommendation at this endpoint use the Login checkpoint.

POST api.ravelin.com/v3/login

timestamp integer required

Unix timestamp with milliseconds (nanoseconds also accepted)

The login used by the customer.

username string required

The username of the customer. This is the unique string that ties this particular customer to the authentication mechanism used. Typically this is the email address.

success boolean required

If the login attempt was successful and access was granted.

authenticationMechanism object required

At least one authentication mechanism must be provided. More than one may be provided. For example a password and a oneTimeCode may be used to authenticate.

Any of the following:

password object optional

Provided if the customer is using a password to authenticate.

social object optional

Provided if the customer authenticates via a social login provider.

oneTimeCode object optional

Provided if a one time code such as those used by Google Authenticator is used.

u2f object optional

Provided if Universal 2nd Factor (U2F) authentication is used, as defined by the FIDO Alliance.

rsaKey object optional

Provided if an RSA key is used, such as a Yubikey.

smsCode object optional

Provided if a one time code was used sent via SMS.

magiclink object optional

Provided if a one time link was sent to the customer via a trusted communication channel.

recaptcha object optional

Provided if reCAPTCHA was performed.

bioMetric object optional

Provided if biometric authentication is used.

pushNotification object optional

Provided if a push notification is sent within an app to authenticate a customer.

customerId string optional

customerId is the unique identifier for a customer. This identifier does not change even if the username is changed. This is optional for login events as you will see failed logins against usernames that do not exist in your system and therefore do not have a customerId. Please send this on login attempts where a customerId is available. If you have a Ravelin payment fraud integration, this should be the same customerId as used there.

app object important

The mobile or web app that this login was done from.

custom object optional

Custom data that is relevant to your domain. This can be any JSON object.

device object optional

While Device is not a required field on the login event, it is highly recommended as it is a vital signal to account breaches. The most important Device fields are deviceId and ipAddress. deviceId can be generated using our JavaScript and mobile libraries.

deviceId string required

The ID of the device used by the customer to trigger this update.

ipAddress string important

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

language string optional

The ISO 639 code of your customer's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

userAgent string important

The browser user-agent string, if the device represents a web browser - window.navigator.userAgent.

model string important

The model/identifier name of the device if the device represents a native app. See here for iOS models: https://www.theiphonewiki.com/wiki/Models and here for Google Play supported models: http://storage.googleapis.com/play_public/supported_devices.csv.

os string important

The operating system that the device is running.

type string optional

The type of device.

One of: computer, phone, or tablet.

manufacturer string optional

The maker of the device.

location object optional

The geolocated position of the device.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

browser string optional

deprecated

The name of the web browser being used, if applicable. Prefer userAgent.

javascriptEnabled boolean optional

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean optional

deprecated

Whether cookies are enabled on the web browser.

screenResolution string optional

deprecated

The resolution of the screen on the device in the format XxY

location object optional

Location is optional as we are aware you will not typically have a location at login time. If you do have location as part of your flow this can be very useful to localise ongoing or repeat attackers.

POST https://api.ravelin.com/v3/login HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "login": {
    "username": "jsmith123@example.com",
    "customerId": "abc-123-XYZ",
    "success": false,
    "authenticationMechanism": {
      "password": {
        "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f",
        "success": false,
        "failureReason": "BAD_PASSWORD"
      },
      "social": {
        "success": false,
        "failureReason": "TIMEOUT",
        "socialProvider": "facebook"
      },
      "oneTimeCode": {
        "success": false,
        "failureReason": "INVALID_CODE"
      },
      "u2f": {
        "success": false,
        "failureReason": "INVALID_KEY"
      },
      "rsaKey": {
        "success": false,
        "failureReason": "INVALID_KEY"
      },
      "smsCode": {
        "phoneNumber": "+447907283546",
        "success": false,
        "failureReason": "INVALID_CODE"
      },
      "magiclink": {
        "transport": "email",
        "phoneNumber": "+447907283546",
        "success": false,
        "failureReason": "INVALID_LINK"
      },
      "recaptcha": {
        "success": false,
        "failureReason": "TIMEOUT"
      },
      "bioMetric": {
        "success": false,
        "failureReason": "TIMEOUT"
      },
      "pushNotification": {
        "success": false,
        "failureReason": "INTERNAL_ERROR"
      }
    },
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "location": {
    "country": "GBR",
    "postalCode": "E1 1AA",
    "latitude": 51.503252,
    "longitude": -0.127899,
    "addresseeName": "John Smith",
    "street1": "123 fake st.",
    "street2": "floor 4, flat 48",
    "neighbourhood": "Hackney",
    "zone": "1",
    "city": "London",
    "region": "California",
    "poBoxNumber": "1234"
  }
}

Response

status integer

The HTTP response status code.

success boolean

If the request was successful this field is true.

timestamp string

A timestamp (ISO 8601) indicating when we finished handling the request.

data object

customerId string

The ID of the customer going through the login process.

action string

Our account takeover recommendation.

Use this to determine how you should handle the login.

Options:

ALLOW - We are confident the activity is from a genuine customer.
REVIEW - We suspect the activity is not from a genuine customer.
PREVENT - We are confident the activity is not from a genuine customer.
PERMIT - Legacy version of ALLOW.
WARN - Legacy version of REVIEW.
BLOCK - Legacy version of PREVENT.

score integer

The account takeover score, a value between 0 and 100. The higher the number the more fraudulent we think the customer is.

source string

The reason for our recommended action.

Do not implement any logic based upon this field as we may add values in the future without warning.

Options:

CLIENT_RULE - The action was based on a rule.
ML - The action was based on our machine learning fraud score.
RATE_LIMIT - This request was rate-limited. The action was based on the default action for rate-limited requests.

scoreId string

A unique ID for this score.

ato object

Further details about the account takeover recommendation.

loginId string

The ID of the login to which this recommendation applies.

action string

Our account takeover recommendation.

Use this to determine how you should handle the login.

Options:

ALLOW - We are confident the activity is from a genuine customer.
REVIEW - We suspect the activity is not from a genuine customer.
PREVENT - We are confident the activity is not from a genuine customer.
PERMIT - Legacy version of ALLOW.
WARN - Legacy version of REVIEW.
BLOCK - Legacy version of PREVENT.

actionSource string

The reason for our recommended action.

Do not implement any logic based upon this field as we may add values in the future without warning.

Options:

CLIENT_RULE - The action was based on a rule.
ML - The action was based on our machine learning fraud score.
RATE_LIMIT - This request was rate-limited. The action was based on the default action for rate-limited requests.

rules object

ruleId integer

The ID of the highest priority rule triggered.

ruleVersion integer

The version of the highest priority rule triggered.

credentialStatus object

customerChanges array

deprecated

changeId string

A unique ID given to the change.

customerId string

The ID of the customer going through the login process.

timestamp string

A timestamp indicating when we finished handling the request.

changeType string

The change type indicates what was actually changed on the customer record.

newValue object

The updated state of the customer record.

device object

The updated state of the customer's IP device.

ipAddr object

The updated state of the customer's IP address.

email object

The updated state of the customer's email.

password object

The updated state of the customer's password.

telephone object

The updated state of the customer's telephone.

deliveryAddress object

The updated state of the customer's delivery address.

billingAddress object

The updated state of the customer's delivery address.

previousValue object

The previous state of the customer record.

device object

The previous state of the customer's device.

ipAddr object

The previous state of the customer's IP address.

email object

The previous state of the customer's email.

password object

The previous state of the customer's password.

telephone object

The previous state of the customer's telephone.

deliveryAddress object

The previous state of the customer's delivery address.

billingAddress object

The updated state of the customer's delivery address.

verificationURL string

A URL given to verify the customer changes.

changeSetId string

An ID that associates multiple changes together.

{
  "status": 200,
  "success": "true",
  "timestamp": "2021-08-27T12:19:31Z",
  "data": {
    "customerId": "39f54f7c-8ed7-41f8-5260-09881f69f675",
    "action": "ALLOW",
    "score": 20,
    "source": "RAVELIN",
    "scoreId": "4fd50782-b9f7-48be-64e1-820c7cf6dd51",
    "ato": {
      "loginId": "login-123",
      "action": "ALLOW",
      "actionSource": "CLIENT_RULE",
      "rules": {
        "passiveAction": "REVIEW",
        "triggered": [
          {
            "ruleId": 123,
            "ruleVersion": 2,
            "triggered": true,
            "description": "This describes the rule.",
            "action": "ALLOW"
          }
        ]
      },
      "ruleId": 123,
      "ruleVersion": 1
    }
  },
  "credentialStatus": {
    "passwordBreached": false,
    "usernameBreached": false
  },
  "customerChanges": [
    {
      "changeId": "9aa92ad0-ee23-4293-7fee-396dc738b195",
      "customerId": "39f54f7c-8ed7-41f8-5260-09881f69f675",
      "timestamp": "2021-08-27T12:19:31.035741497Z",
      "changeType": "DEVICE",
      "newValue": {
        "device": {
          "deviceId": "d61096b5-4ef8-4404-6666-eb9e8df1d754",
          "deviceType": "phone",
          "deviceManufacturer": "Samsung",
          "deviceModel": "SM-G960F",
          "deviceOS": "android",
          "ipAddress": "1c14:d7a:124f:3a00:400:cb7b:e4aa:af92",
          "userAgent": "Mozilla/5.0 (Linux; Android 10; SM-G960F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.152 Mobile Safari/537.36",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "ipAddr": {
          "ipAddress": "123.45.67",
          "timestamp": "2021-08-27T12:19:31.035741497Z",
          "city": "London",
          "countryISO": "GBR",
          "continentISO": "EU",
          "isp": "BT"
        },
        "email": {
          "email": "test@ravelin.com",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "password": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "telephone": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "deliveryAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.01",
          "timestamp": "2021-08-27T12:19:31Z"
        },
        "billingAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.0",
          "timestamp": "2021-08-27T12:19:31Z"
        }
      },
      "previousValue": {
        "device": {
          "deviceId": "d61096b5-4ef8-4404-6666-eb9e8df1d754",
          "deviceType": "phone",
          "deviceManufacturer": "Samsung",
          "deviceModel": "SM-G960F",
          "deviceOS": "android",
          "ipAddress": "1c14:d7a:124f:3a00:400:cb7b:e4aa:af92",
          "userAgent": "Mozilla/5.0 (Linux; Android 10; SM-G960F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.152 Mobile Safari/537.36",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "ipAddr": {
          "ipAddress": "123.45.67",
          "timestamp": "2021-08-27T12:19:31.035741497Z",
          "city": "London",
          "countryISO": "GBR",
          "continentISO": "EU",
          "isp": "BT"
        },
        "email": {
          "email": "test@ravelin.com",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "password": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "telephone": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "deliveryAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.0",
          "timestamp": "2021-08-27T12:19:31Z"
        },
        "billingAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.0",
          "timestamp": "2021-08-27T12:19:31Z"
        }
      },
      "verificationURL": "http://api/v2/change/verify?id=cmF2vbWVRlc3RCpzlhYTkyYWQwLRjNzM4YjN1cFsR1dHWVLWxZueELZWxpbnLTlvZ2ltNDI5My03ZmVlE5NQuLW3TCp2yM5NmZ0MjM==",
      "changeSetId": "aeb87294-a02d-4746-7d45-34770d51f308"
    }
  ]
}

Feedback

Was this page helpful?