Client Action APIs

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.
• 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": "92549020",
  "score": 0.98,
  "attack_type": "fake_account",
  "attack_patterns": [
    "spamming"
  ],
  "rule_id": "84734834",
  "action_name": "account_suspension",
  "timestamp": "2022-06-24T15:13:52.164Z",
  "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. In such cases, you have two options for triggering an API call:

1. Single call for all users: You can make a single API call, including information for all users impacted by the cluster incident.
2. Individual calls for each user: Alternatively, you can trigger individual API calls for each user within the cluster incident.

The default fields included in the request body for a clustered incidents are as follows:

• user_id: 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.
• 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": ["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": {
    "cluster_key": "583cbaeb-5f73-400c-99a8-2cce4a9fde9d",
    "cluster_key_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"
    ]
}

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"
    },
    "group_users": true,
}

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!