Truth Data System

📘

Truth Data documentation was significantly updated as of 20-Oct-2022. You now send Truth Data to Arkose via the Arkose Command Center & the new Truth Data API as described on this page.

Overview

To detect attacks, Arkose Detect uses many data points collected on both the client and server sides. Still, it is not always obvious whether a session is valid or an attack. As a customer though, you see how sessions turn out based on how the end-user interacted with your platform. Arkose’s Truth Data system lets you provide this feedback to Arkose via the Arkose Command Center. This feedback:

  • Provides Arkose with additional data points to improve our detection abilities.
  • Helps customers understand why a session was a false positive via Command Center dashboards dedicated to Truth Data.

Sending Truth Data Via The Arkose Command Center

Follow these steps to upload truth data to Arkose via our Command Center:

  1. Go to the Arkose Command Center and login.

  2. In the left vertical menu bar, navigate to Settings, and then to Truth Data, as shown below. If you don’t see the Truth Data tab, please contact Arkose to enable it.

  3. Use the DOWNLOAD SAMPLE FILE tab to download a file with the column headers that Arkose expects. Using this as a template for your data file greatly reduces the chances of an upload failure.

  4. After downloading the sample file, fill in the data you want to upload to Arkose and, if desired, rename it to what you consider appropriate. The mandatory and optional fields shown here are described below in the Truth Data API Fields table.

  5. When you finish entering your data, save it and click on the UPLOAD DATA tab. You will see an Import data from CSV… message as shown below. Select the file you want to upload and click the UPLOAD FILES button. Note that you can only upload one file at a time. The maximum file size is 100 MB. After uploading, you will see a status screen as shown below. Note that it may take up to 30 minutes to upload the file.

  1. Once the file is successfully uploaded, a Zendesk ticket file automatically opens under your Arkose account. You will be notified of any Arkose SOC analysis, recommendations, or telltale modifications or creations via the Zendesk ticket.

Sending Truth Data via New API

API URL: https://client-api.arkoselabs.com/truth_data_api/v1/stream_data

To automatically send Truth Data to Arkose, please follow the steps below:

Step 1: Create an API Access Token via Arkose Command Center. You can do this by navigating to the sidebar > Tokens > Create Token. Add a description for your use.

Step 2: Use the generated token to invoke Arkose Labs Truth Data API. The request body needs to be as follows:

Request Header:
{
   Authorization: [Basic U3VuYWluYTpDNXR2akJYMG1abHZWM0FKQn….] // token
}
Request Body:
{
   "arkose_session_id": "32560e3747191b697.1304102202", // mandatory
   "public_key": "D6A0C8E8-F7E7-4A39-A515-5BE578369101", // mandatory
   "session_create_timestamp": "2021-10-30 12:31:29", // optional
   "decision_timestamp": "2021-10-30 12:31:30", // optional
   "is_legit": 0, // mandatory
   "event_type": 2, // optional
   "fraud_category": 3, // optional
   "fraud_type": 2 // optional
}

📘

Please let your account representative know if you can’t see the Tokens tab on Portal.

Truth Data API Fields

For the optional fields that accept string enums, Arkose improves our analysis by doing a strict validation against the defined enums. Please contact us if you want an additional enum added to the list.

FieldMandatory/OptionalDescriptionFormat
arkose_session_idMandatoryA primary link between the truth data and its Arkose session.11663602dda317f65.6750167505
public_keyMandatoryPublic key for which the truth data is being shared.1F662B05-B798-D2A3-B687-C1D43DD4EB76
session_create_timeOptionalThe date and timestamp when the customer created the session.YYYY-MM-DD HH:MM:SS
decision_timeOptionalThe date and timestamp when the customer decided if the session was good or bad.YYYY-MM-DD HH:MM:SS
is_legitMandatoryA high level overview of whether the customer considers the session legit or non-legit.0 (indicates non-legit)
1 (indicates legit)
event_typeOptionalStage of a user’s lifecycle where the event occurred. This data helps Arkose create appropriate algorithms tailored to the specific event type, thus reducing false positives.1 (registration)

2 (login)

3 (password_reset)

4 (account_settings)

5 (transaction)
fraud_categoryOptionalThe overarching category that the fraud falls in. This information helps Arkose tune the appropriate algorithm’s parameters, thus reducing false positives.1 (automation)

2(fraud_farm)

3 (human_driven)
fraud_typeOptionalA granular view of the committed fraud. This helps Arkose create and improve algorithms tailored to specific fraud type and/or verticals, improving our overall accuracy.1 (fake_email)

2 (fake_phone_number)

3 (stolen_financial_instrument)

4 (fraudulent_chargeback)

5 (social_engineering_attempt)