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)

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 /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
Show definition
credentialStatus object
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