Client Action APIs
  • 05 Jun 2024
  • Dark
    Light

Client Action APIs

  • Dark
    Light

Article summary

What are Client Actions

Client actions in Account Defender refer to the APIs that can be utilized as responses to incidents. When a user matches an existing policy, an authorized HTTPS call will be made to your public API. These client actions can be performed on both single incidents and cluster incidents, and are the same for any attack type.

Client actions for single incidents

A single incident involves a response triggered for an individual user. The default fields included in the request body for a single incident are as follows:

  • user_id: The user’s account ID.
  • score: The severity score assigned to the incident (0-1 float number).
  • attack_type: The type of attack detected (ato / fake_account).
  • attack_patterns: Information about the patterns associated with the attack.
  • rule_id: The identifier of the rule triggered for this incident.
  • rule_name: The name of the rule that triggered the API request as configured in the policy rules management.
  • action_name: The name of the action as configured for single incidents.
  • timestamp: The timestamp of the incident.

Example of single incident request body:

{
    "user_id": "12345",
    "score": 0.99,
    "attack_type": "ato",
    "attack_patterns": [
        "non_withdrawing_account"
    ],
    "rule_id": "cfa7d19b-3b06-4514-9924-d1eb77fc9791",
    "rule_name": "ATO with high score",
    "action_name": "Reset password",
    "timestamp": "2024-05-12T15:11:27.745Z",
    "additional": {
        "city": "Tel Aviv",
        "country": "IL",
        "ip": "15.5.133.81",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.124 Safari/537.36 Edg/102.0.1245.44"
    }
}

Client actions for clustered incidents

Clustered incidents involve multiple users affected by the same attack pattern. The default fields included in the request body for a clustered incidents are as follows:

  • user_ids: Array of the account IDs of the users in the cluster.
  • score: The severity score assigned to the cluster (0-1 float number).
  • attack_type: The type of attack detected (ato / fake_account).
  • rule_id: The identifier of the rule triggered the cluster.
  • rule_name: The name of the rule that triggered the API request as configured in the policy rules management.
  • action_name: The name of the action as configured for clustered incidents.
  • timestamp: The timestamp of the incident.
  • cluster_key: the unique identifier value of the cluster.
  • cluster_key_type: the unique identifier type of the cluster.

Example of clustered incident request body:

{
    "user_ids": ["123","456","789"],
    "score": 1,
    "attack_type": "ato",
    "attack_patterns": null,
    "rule_id": "39b524c9-f172-4d5c-ab1d-472a14c035da",
    "rule_name": "ATO with high score",
    "action_name": "Reset password",
    "timestamp": "2024-05-12T16:48:08.362344483Z",
    "additional": {
        "cluster_key": "14720032442281872288",
        "cluster_key_type": "device"
    }
}

Client actions for network incidents

Network incidents involve multiple users affected by the same attack. In such cases a single call is made including information about all of the impacted users.
The default fields that are included in the request body for a network incident are as follows:

  • user_ids: Array of the account IDs of the users in the network.
  • score: The severity score assigned to the network (0-1 float number).
  • attack_type: The type of attack detected (ato / fake_account).
  • rule_id: The identifier of the rule that triggered the network.
  • action_name: The name of the action as configured for network incidents.
  • timestamp: The timestamp of the incident.
  • network_id: The unique identifier value of the network.
  • network_type: The type of the network.

Example of network attack incident request body:

{
  "user_ids": ["92549020", "92549021", "92549022"],
  "score": 0.98,
  "attack_type": "fake_account",
  "rule_id": "84734834",
  "action_name": "account_suspension",
  "timestamp": "2022-06-24T15:13:52.164Z",
  "additional": {
    "network_id": "320",
    "network_type": "vid",
  }
}

Configuration

To ensure successful integration, please provide the following information for the API call:

  • name: the name of the action that will be sent as part of the payload and will be used in reports, exports, etc.
  • display_name: will appear in the Account Defender screens (Business Insights, Audits, Dashboard etc.)
  • method: HTTP method (as described here)
  • URL: The endpoint URL where the HTTPS call should be made.
  • Authorization: The necessary authentication token or credentials required to access your API.
  • additional_params: The fields to include in the request payload

Example of client action configuration for single incidents:

{
    "name" : "https_example_client_action",
    "display_name" : "What this action does"
    "URL" : "https://customer-public-site.com/account-defender-api-route",
    "method" : "POST",
    "headers" : {
        "Authorization" : "Bearer q_dfuhf47hr4uhuehf_eirj3uhr34_Yus",
        "Content-Type" : "application/json"
    },
    "additional_params" : [
        "ip",
        "user_agent",
        "country",
        "city"
    ]
}
Note

For single activities, you have the flexibility to include any additional fields available in the Details Account Activities table (Investigation page) to the payload. To do so, add the required fields to the "additional_params" array in the configuration JSON)

Example of client action configuration for clustered incidents:

{
   "name":"https_example_client_action_clustred",
   "display_name":"What this action does (clustered)",
   "URL":"https://customer-public-site.com/account-defender-api-route-cluetred",
   "method":"POST",
   "headers":{
      "Authorization":"Bearer q_dfuhf47hr4uhuehf_eirj3uhr34_Yus",
      "Content-Type":"application/json"
   }
}

Testing

To validate the integration of client action APIs, you can use the request form to perform test requests.
If you have any further questions or need assistance, please feel free to reach out to your customer success manager. We're here to help!


Was this article helpful?