Login

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

Account takeover recommendations need to be enabled on your account before they can be used. Please speak to your account manager about enabling account takeover recommendations.

POST api.ravelin.com/v3/login

Show all definitions
timestamp integer required

Unix timestamp with milliseconds (nanoseconds also accepted)

login object required

The login used by the customer.

Show definition
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.

Show definition
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.

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

{
  "timestamp": 1512828988826,
  "login": {
    "username": "jsmith123@example.com",
    "success": false,
    "authenticationMechanism": {
      "password": {
        "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f",
        "emailPasswordSHA256": "1869a65c576bf844f00b2ef88aa352ffd2d5b348a383720772c0c416470fc74e",
        "passwordSHA1SHA256": "fe38f41dc87ffd6b26e432b7f9cb3475d5c1899edacb453c70ac1dcaafd73d26",
        "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"
    },
    "customerId": "abc-123-XYZ"
  },
  "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

Show all definitions
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
Show definition

Contains details about whether the credentials have been found in our breached credentials database.

Show definition
customerChanges array
deprecated
Show definition
{
  "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

© Ravelin Technology Ltd. All rights reserved