Taking actions on secured entities

Single security event

URI - POST

To use this endpoint, send a POST request to perform a single action on a specific security event or multiple events (a single action is supported per multiple events): /action/entity

Request

The request includes HTTP headers (obtained from the authentication/authorization process and used to sign the request) with request parameters posted on the request body.

Request Headers

Header	Type	Required	Format	Description/Sample
x-av-req-id	String	Yes	UUID – Generated and supplied on the request.	d290f1ee-6c54-4b01-90e6-d701748f085 1
Authorization	Bearer Token	Yes	Bearer <API Access Token>	A string Bearer followed by the API Access Token. See Generating API Access Token. For example, assuming that the API Access Token is 1234, the Bearer Token will be Bearer 1234

Header

Type

Required

Format

Description/Sample

x-av-req-id

String

Yes

UUID – Generated and supplied on the request.

d290f1ee-6c54-4b01-90e6-d701748f085 1

Authorization

Bearer Token

Yes

Bearer <API Access Token>

A string Bearer followed by the API Access Token. See Generating API Access Token.

For example, assuming that the API Access Token is 1234, the Bearer Token will be Bearer 1234

Request String Parameters

None

Request Body

All applicable request parameters are posted on the request body JSON:

Copy

{
    "requestData": 
    {
        "entityIds": ["string"], 
        "entityActionName": ["string"],
        "entityActionParam": ["string"]
    }
}

Request Body Parameters

The JSON parameters:

Parameter	Type	Required	Description/Sample
requestData	Object		A container for action request.
entityIds	Array of String	Yes	List of unique event identifiers on which the action is performed.
eventActionName	String	Yes	The name of the action to execute (For example, quarantine).
eventActionParam	String		Additional parameter relevant to the action (For example, reason, duration).

Request sample (CURL) format

This request sample shows URI base in USA region. For URI base in other regions, see URLs and URL Base.

Copy

curl -X POST -H "Accept: application/json" \
    -H "x-av-req-id: d290f1ee-6c54-4b01-90e6-d701748f3351" \
    -H "Authorization: Bearer 2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497" \
    -d "{"requestData": {"entityIds": ["6bb51619b0bb6a5a2ed3315ea1968435"],"entityActionName": ["quarantine"],"entityActionParam": [""]} }” \
    https://cloudinfra-gw-us.portal.checkpoint.com/app/hec-api/v1.0/action/entity

This request sample quarantines the SaaS entity whose Email Security entity ID is “6bb51619b0bb6a5a2ed3315ea1968435”

Response

The response obtained from the service includes an HTTP response code and JSON formatted structure. The JSON structure contains response envelope and response data which includes a detailed response code for the action per each entityId in the request.

Response Structure

A valid response obtained from the service (JSON format):

Copy

{
    "responseEnvelope": 
        { 
            "requestId": "string", 
            "responseCode": integer,
            "responseText": "string",
            "additionalText": "string", 
            "recordsNumber": integer,
            "totalRecordsNumber": integer,
            "scrollId": "string"
        },
    "responseData": 
        [
            {
                "entityId": "string",
                "taskId": "integer"
            }
        ]
}

Response Parameters

These are the response parameters:

Parameter		Type	Description
responseEnvelope		Object	A container of metadata properties.
	requestId	String	Unique identifier for tracking the request-response cycle.
	responseCode	Integer	Status code HTTP API code response.
	responseTest	String	Human-readable message about the response status.
	additionalText	String	Need to see an example.
	recordsNumber	Integer	Number of records found.
	totalRecordsNumber	Integer	Total number of records.
	scrollId	String	Pagination id to get next batch of records.
responseData		Object	Array of security event identifiers and their corresponding action response codes and additional text
	entityId	String	ID of the impacted or triggering entity (For example, email Id).
	taskId	Integer	Id of the relevant task.

Response Sample

A valid response from the service:

Copy

{
    "responseEnvelope": 
        {
            "requestId": "d290f1ee-6c54-4b01-90e6-d701748f3351", 
            "responseCode": 0,
            "responseText": "success", 
            "additionalText": "", 
            "recordsNumber": 1,
            "totalRecordsNumber": 1,
            "scrollId": "9898989898"
        },
    "responseData": 
        [
            {
            "entityId": "7ded0371a3e1475c9a877e452f23a049", 
            "taskId": "123445311234"
            }
        ]
}