API Reference > Endpoints > Login

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)

required

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 /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.

One of: ALLOW, REVIEW, PREVENT, PERMIT (legacy), WARN (legacy), or BLOCK (legacy).

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 source of the action recommendation. Do not implement any logic based upon this field, we may add values in the future without warning.

scoreId string

A unique ID for this score.

ato object

Further details about the account takeover recommendation.

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?