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

deprecated

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

javascriptEnabled boolean

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean

deprecated

Whether cookies are enabled on the web browser.

screenResolution string

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": "UNKNOWN_USERNAME"
      },
      "social": {
        "success": false,
        "failureReason": "SOCIAL_FAILURE",
        "socialProvider": "facebook"
      },
      "oneTimeCode": {
        "success": false,
        "failureReason": "AUTHENTICATION_FAILURE"
      },
      "u2f": {
        "success": false,
        "failureReason": "INVALID_KEY"
      },
      "rsaKey": {
        "success": false,
        "failureReason": "INTERNAL_ERROR"
      },
      "smsCode": {
        "phoneNumber": "+447907283546",
        "success": false,
        "failureReason": "INVALID_CODE"
      },
      "magiclink": {
        "transport": "email",
        "phoneNumber": "+447907283546",
        "success": false,
        "failureReason": "RATE_LIMIT"
      },
      "recaptcha": {
        "success": false,
        "failureReason": "TIMEOUT"
      },
      "bioMetric": {
        "success": false,
        "failureReason": "BANNED_USER"
      },
      "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

success string

timestamp string

data object

credentialStatus object

customerChanges array

{
  "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": {
      "action": "PERMIT"
    }
  },
  "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"
        }
      },
      "previousValue": {
        "device": {
          "deviceId": "0c999b50-db07-46a0-629f-f55b89dc1dc0",
          "deviceType": "phone",
          "deviceManufacturer": "Apple",
          "deviceModel": "iPhone",
          "deviceOS": "ios",
          "ipAddress": "92.41.191.36",
          "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1",
          "timestamp": "2021-08-27T12:19:27.26181816Z"
        }
      },
      "verificationURL": "http://api/v2/change/verify?id=cmF2vbWVRlc3RCpzlhYTkyYWQwLRjNzM4YjN1cFsR1dHWVLWxZueELZWxpbnLTlvZ2ltNDI5My03ZmVlE5NQuLW3TCp2yM5NmZ0MjM==",
      "changeSetId": "aeb87294-a02d-4746-7d45-34770d51f308"
    }
  ]
}

Feedback

Was this page helpful?