Alert Endpoints

Alerts notify you of security events, policy violations, and operational issues that require attention. VeraID generates alerts automatically based on anomaly detection, policy enforcement, credential lifecycle events, and behavioral analysis.

Alert Types

Type	Description	Default Severity
ANOMALY_DETECTED	Unusual behavior detected by the anomaly detection engine	HIGH
POLICY_VIOLATION	An identity attempted an action that violates an active policy	MEDIUM
CREDENTIAL_EXPIRING	A credential is approaching its expiration date	LOW
HIGH_RISK_IDENTITY	An identity’s risk score has exceeded the configured threshold	HIGH
UNUSUAL_ACTIVITY	Activity patterns deviate significantly from the established baseline	MEDIUM
RATE_LIMIT_EXCEEDED	An identity has exceeded its configured rate limit	MEDIUM

---

List Alerts

Retrieve a paginated list of alerts with optional filters.

GET /api/v1/alerts

Query Parameters

Parameter	Type	Description
status	string	Filter by status: ACTIVE, ACKNOWLEDGED, RESOLVED
severity	string	Filter by severity: CRITICAL, HIGH, MEDIUM, LOW
type	string	Filter by alert type (see table above)
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://app.veraid.io/api/v1/alerts?status=ACTIVE&severity=HIGH" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "alert_abc123",
      "type": "ANOMALY_DETECTED",
      "severity": "HIGH",
      "status": "ACTIVE",
      "title": "Anomalous Secret Access Pattern",
      "description": "Identity 'ci-deploy-service' accessed 47 secrets in 2 minutes. Baseline for this identity is 3-5 secrets per hour.",
      "identity": {
        "id": "id_xyz789",
        "name": "ci-deploy-service",
        "type": "CI_CD",
        "riskScore": 89
      },
      "metadata": {
        "baselineAccessRate": "3-5/hour",
        "observedAccessRate": "47/2min",
        "anomalyScore": 0.97,
        "affectedSecrets": 47
      },
      "triggeredAt": "2026-03-19T10:15:00Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null
    },
    {
      "id": "alert_def456",
      "type": "HIGH_RISK_IDENTITY",
      "severity": "HIGH",
      "status": "ACTIVE",
      "title": "Identity Risk Score Exceeded Threshold",
      "description": "Identity 'legacy-api-service' risk score increased to 92 (threshold: 80). Contributing factors: stale credentials, excessive permissions, no recent activity.",
      "identity": {
        "id": "id_legacy001",
        "name": "legacy-api-service",
        "type": "SERVICE_ACCOUNT",
        "riskScore": 92
      },
      "metadata": {
        "previousRiskScore": 65,
        "currentRiskScore": 92,
        "threshold": 80,
        "riskFactors": [
          "credential_age_365d",
          "excessive_permissions",
          "no_activity_90d",
          "no_owner_assigned"
        ]
      },
      "triggeredAt": "2026-03-19T08:00:00Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1,
    "hasMore": false
  }
}

---

Acknowledge Alert

Mark an alert as acknowledged, indicating that a team member is aware of the issue and is investigating.

POST /api/v1/alerts/{id}/acknowledge

Request Body

Field	Type	Required	Description
note	string	No	Optional note about the acknowledgement

Example Request

curl -X POST https://app.veraid.io/api/v1/alerts/alert_abc123/acknowledge \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Investigating - appears to be related to the batch migration job running at 10:15 UTC"
  }'

Example Response

{
  "id": "alert_abc123",
  "type": "ANOMALY_DETECTED",
  "severity": "HIGH",
  "status": "ACKNOWLEDGED",
  "title": "Anomalous Secret Access Pattern",
  "acknowledgedAt": "2026-03-19T10:20:00Z",
  "acknowledgedBy": {
    "id": "usr_admin001",
    "name": "Alice Johnson",
    "email": "alice@company.com"
  },
  "note": "Investigating - appears to be related to the batch migration job running at 10:15 UTC"
}

Note

Acknowledging an alert stops escalation notifications for that alert. If the alert is not resolved within the configured escalation window, notifications resume.

---

Resolve Alert

Mark an alert as resolved, indicating that the underlying issue has been addressed.

POST /api/v1/alerts/{id}/resolve

Request Body

Field	Type	Required	Description
resolution	string	No	Description of how the alert was resolved
rootCause	string	No	Root cause analysis

Example Request

curl -X POST https://app.veraid.io/api/v1/alerts/alert_abc123/resolve \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "Confirmed that the batch migration job legitimately accessed 47 secrets as part of the planned data migration. Job completed successfully.",
    "rootCause": "Scheduled batch migration job accessing configuration secrets for each migrated service. Expected behavior - adding tag to identity to suppress future alerts during migration windows."
  }'

Example Response

{
  "id": "alert_abc123",
  "type": "ANOMALY_DETECTED",
  "severity": "HIGH",
  "status": "RESOLVED",
  "title": "Anomalous Secret Access Pattern",
  "acknowledgedAt": "2026-03-19T10:20:00Z",
  "acknowledgedBy": {
    "id": "usr_admin001",
    "name": "Alice Johnson",
    "email": "alice@company.com"
  },
  "resolvedAt": "2026-03-19T10:45:00Z",
  "resolvedBy": {
    "id": "usr_admin001",
    "name": "Alice Johnson",
    "email": "alice@company.com"
  },
  "resolution": "Confirmed that the batch migration job legitimately accessed 47 secrets as part of the planned data migration. Job completed successfully.",
  "rootCause": "Scheduled batch migration job accessing configuration secrets for each migrated service. Expected behavior - adding tag to identity to suppress future alerts during migration windows.",
  "timeToAcknowledge": "5m",
  "timeToResolve": "30m"
}

---

Alert Lifecycle

Alerts progress through the following states:

ACTIVE → ACKNOWLEDGED → RESOLVED

Transition	Trigger	Description
ACTIVE → ACKNOWLEDGED	Manual	A team member acknowledges the alert
ACTIVE → RESOLVED	Manual	The alert is resolved without prior acknowledgement
ACKNOWLEDGED → RESOLVED	Manual	The acknowledged alert is resolved

Tip

Configure alert routing rules to send different alert types and severities to the appropriate messaging channels and on-call teams. See the Messaging & Notifications documentation for setup instructions.

Alert Severity Levels

Severity	Description	Expected Response
CRITICAL	Immediate threat requiring urgent action	Respond within 15 minutes
HIGH	Significant risk requiring prompt investigation	Respond within 1 hour
MEDIUM	Moderate risk requiring attention	Respond within 4 hours
LOW	Informational or low-impact issue	Respond within 24 hours