API Reference
Overview
The EchelonGraph REST API lets you integrate cloud security intelligence into your workflows, CI/CD pipelines, and existing tools. All endpoints are documented in our OpenAPI specification, available to customers upon request.
Authentication
All API requests require a valid bearer token. Authenticate via the login endpoint to receive an access token and refresh token pair. If MFA is enabled on your account, a second verification step is required.
Rate Limits
The API enforces a 500 requests/second limit per source IP across the /api/v1 surface — a per-IP abuse guard, not a per-plan quota. Requests over the limit receive a 429 Too Many Requests response; trusted first-party callers are exempt.
Rate limit headers are included on every response so you can track usage programmatically.
Pagination
List endpoints support pagination via limit with offset (or a keyset cursor); some endpoints also accept page/page_size. Responses include a total count for easy navigation.
Key Capabilities
Cloud Assets
Query your complete cloud asset inventory across all connected providers. Filter by asset type, region, and risk score. Register and manage cloud account connections.
Blast Radius & Attack Graph
Retrieve the interactive attack surface graph — nodes, links, and traversal paths. Specify depth to compute the tenant's blast-radius attack graph.
Vulnerabilities & CVEs
Access your CVE feed with severity and status filtering. View remediation recommendations with priority rankings and track remediation workflow progress.
Alerts & Detection
List and manage security alerts by severity and status. Alerts are generated from open findings across your environment.
Compliance & Reports
Retrieve compliance scores per framework. Generate reports (executive, compliance, scan, alert, asset inventory) in CSV or JSON format with configurable date ranges.
Risk Scoring
Access risk score breakdowns by category — vulnerabilities (CVEs), misconfigurations, compliance, blast radius, and SLA breaches — for a unified view of your security posture.
Real-Time Events
EchelonGraph supports real-time event delivery via WebSocket connections, pushing updates as they happen:
- Asset discovery
- Vulnerability detections
- Breach alerts
- Compliance drift
- System notices
Webhooks
Register webhook endpoints to receive event notifications at your own URLs. All webhook payloads are signed with HMAC-SHA256 for verification, ensuring payload integrity.
Supported events include critical and high alerts, CVE matches, scan completion, compliance drift, asset discovery, finding creation, and report readiness.
User Provisioning (SCIM 2.0)
Automate user lifecycle management directly from your identity provider. EchelonGraph's SCIM 2.0 integration supports user listing, creation, and group synchronization with any SCIM-compliant IdP.
Audit Trail
Query the immutable audit log to review every authentication event, permission change, data export, and configuration modification — with full filtering by action type, user, and date range.