Incidents API

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

The Incidents API lets you view statistics for security incidents related to abuse detection.

Parameters in example API calls

The following sections give examples of API calls that use the Incidents API. The API calls contain the following variable parameters:

  • ORG is your organization.
  • ENV is the environment in which you want scores to be calculated.
  • INCIDENT_UUID is the UUID for the incident.
  • $TOKEN is the environment variable for an OAuth access token.

List incidents and get their details

The following examples show how to list incidents and get their details.

Example: List all incidents for an environment

To list all incidents for an environment, send the following request:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityIncidents" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

See the SecurityIncident reference page for descriptions of the request and response.

Example: Get details for a specific incident

To get the details for a specific incident, send a request like the following:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityIncidents/INCIDENT_UUID" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

where INCIDENT_UUID is the UUID for the incident, which is returned in the name field by the call shown in Example: List all incidents for an environment.

See the SecurityIncident reference page for descriptions of the request and response.

Archiving incidents

To help you distinguish between the incidents you have already investigated from those that you haven't, you can archive the incidents that no longer require you attention. Archiving incidents has the following effects:

  • In the Apigee UI, archived incidents are not displayed in the Environment details > Incidents list (provided that Include archived incidents is not selected).
  • In the API, when you make a call to list all incidents, archived incidents have the following line: 
    "observability": "ARCHIVED"

    You can use the "observability" field to to filter out archived incidents from a list of incidents.

    The possible values for "observability" are:

    • ACTIVE
    • ARCHIVED

Archived incidents are not deleted: you can always unarchive them, which changes the incident's "observability" to ACTIVE.

The following examples show how to archive and unarchive incidents.

Archive an incident

To archive an incident, send a request like the following:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityIncidents/INCIDENT_UUID?updateMask=observability" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"name": "organizations/ORG/environments/ENV/securityIncidents/INCIDENT_UUID",
            "observability": "ARCHIVED"}' \
       -X PATCH

This returns a response like the following:

{
    "name": "INCIDENT_UUID",
    "displayName": "Multi type attack from US",
    "firstDetectedTime": "2023-04-04T17:00:00Z",
    "lastDetectedTime": "2023-09-12T03:10:00Z",
    "detectionTypes": [
      "Advanced Anomaly Detection",
      "OAuth Abuser"
    ],
    "trafficCount": "4052130",
    "containsMlAbuses": false,
    "riskLevel": "MODERATE",
    "observability": "ARCHIVED"
}

The last line, "observability": "ARCHIVED", shows that the incident has been archived.

Unarchive an incident

To unarchive an incident, use the same call as in the previous section, but use the line 

"observability": "ACTIVE"

Filter incidents by archive status

The next example filters the results of a call to list incidents so that only active incidents are returned.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityIncidents?filter=observability=\"ACTIVE\"" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

This returns a result like the following.

{
  "securityIncidents": [
    {
      "name": "1850fbb9-53a9-44e7-8893-f0b0c987d55e",
      "displayName": "Multi type attack from US",
      "firstDetectedTime": "2023-04-04T17:00:00Z",
      "lastDetectedTime": "2023-09-12T03:10:00Z",
      "detectionTypes": [
        "Advanced Anomaly Detection",
        "OAuth Abuser"
      ],
      "trafficCount": "4052130",
      "containsMlAbuses": false,
      "riskLevel": "MODERATE",
      "observability": "ACTIVE"
    }
  ],
  "nextPageToken": "ClAKAjUwEj1saXN0U2VjdXJpdHlJbmNpZGVudC9hcGlzZWN1cml0eS1tbHRlc3QtYXV0b3B1c2gvZGVmYXVsdC1wcm9kGgsI_KW1qQYQ6fqSDg"
}

Archive or unarchive multiple security incidents

To archive or unarchive more than one security incident, enter a command like the following:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityIncidents:batchUpdate" \
       -X POST \
       -d '{"requests": 
        [{"security_incident": {"name": "organizations/apisecurity-mltest-autopush/environments/default-prod/securityIncidents/INCIDENT_UUID1", "observability": "ARCHIVE"}, "update_mask": "observability"}, 
         {"security_incident": {"name": "organizations/apisecurity-mltest-autopush/environments/default-prod/securityIncidents/INCIDENT_UUID2", "observability": "ARCHIVE"}, "update_mask": "observability"}]}'

Limitations on the Security Incidents API

The Security Incidents API has the following limitations:

  • Incidents are stored for a maximum of 14 months.
  • ListIncidents supports filters only for the following:
    • first_detected_time
    • last_detected_time
    • apiproxy
  • When you first enable Advanced API for an organization, or later re-enable it, there will be a delay while events are clustered into incidents. After that, incidents are recalculated periodically.