Logins

Verify logins by analyzing the behavioral pattern of each user and matching it to in-app login history. Logins initiated at unfamiliar locations will increase the Incognia risk score and can be used to trigger step-up authentication.

We secure digital logins by matching the historical location fingerprint and the login history of the initiating user, to their real-time location. Logins initiated at unfamiliar locations will result in a higher risk score.

Prevent fraudsters from taking over user accounts by continually analyzing user location behavior. If Incognia detects suspicious location activity you can trigger additional authentication to confirm the user is legitimate.

Assess new login

POST

https://api.incognia.com/api/v2/authentication/transactions

This method registers a new login for the given installation and account with the available information, returning a risk assessment and the evidence behind it.

Request

Headers

Content-Type	string	Required	application/JSON
Authorization	string	Required	Bearer token generated in Authenticating section.

Body Parameters

installation_id	string	Required	Installation ID of the device from which the signup originates.
type	string	Required	Type of the assessment. The login type is supported for this case.
account_id	string	Required	ID of the user account performing the login attempt.

Response

200: OK

The login was assessed successfully

{
  "id": "96fafbb9-93af-433a-b047-af1f6fc3c279",
  "risk_assessment": "low_risk",
  "reasons": [
    {
      "code": "trusted_location",
      "source": "local"
    }
  ],
  "evidence": {
    "device_model": "LM-X520",
    "known_account": true,
    "location_services": {
      "location_permission_enabled": true,
      "location_sensors_enabled": true
    },
    "device_integrity": {
      "probable_root": false,
      "emulator": false,
      "gps_spoofing": false,
      "from_official_store": true
    },
    "device_fraud_reputation": "unknown",
    "device_behavior_reputation": "unknown",
    "distance_to_trusted_location": 3.4356838410826773,
    "last_location_ts": "2022-04-25T13:33:54.285Z",
    "sensor_match_type": "wifi_connection",
    "account_integrity": {
      "recent_high_risk_assessment": false
    },
    "accessed_accounts": 1,
    "app_reinstallations": 1,
    "first_device_login_at": "2022-04-20T12:28:44.433318Z",
    "first_device_login": false
  },
  "device_id": "dOgLG4Sm8wRIeyWRyl_-ty-ofSXgZOCACnx1w7T4JLeQAOgRt_7trL24yGmfU5JSR1JEZMAzG-JOtXNFhT3h2A"
}

400: Bad Request

The request was malformed (missing required fields, invalid fields). The response body will contain error details.

{
  "errors": [
    "missing installation_id"
  ]
}

403: Forbidden

The provided token does not have the required permissions.

Empty.

500: Internal Server Error

Some internal error happened. Try again or, if the problem persists, contact us.

Empty.

Sample login request

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
  "type": "login"
}

Sample cURL:

curl -XPOST -H "Content-type: application/json" -H "Authorization: Bearer <token>" -d @body.json "https://api.incognia.com/api/v2/authentication/transactions"

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response field	Type	Description
id	string	Unique identifier for the login event.
risk_assessment	enum	The risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments.
reasons	array	The reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidence	object	The supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_id	string	Unique identifier for the user's device.

Register a new login without evaluating it

To register a login without evaluating its risk assessment, add the ?eval=false query parameter. The full URL becomes:

https://api.incognia.com/api/v2/authentication/transactions?eval=false

Turning off the risk assessment evaluation allows you to register a new login, but the response will be an empty JSON (i.e., {}). For instance, if you're using the risk assessment only for some logins you still should register all the other ones: this will avoid any bias on the risk assessment computation.