Skip to content

API.md

Latest commit

 

History

History
760 lines (639 loc) · 12 KB

API.md

File metadata and controls

760 lines (639 loc) · 12 KB

EdgeAI Telemetry - API Documentation

Complete REST API reference for EdgeAI Telemetry v0.2.0

Base URL

http://localhost:8080/api/v1

Authentication

Most endpoints require authentication via Bearer token in the Authorization header:

Authorization: Bearer <jwt-token>

Authentication Endpoints

Login

POST /auth/login

Request body:

{
  "email": "admin@example.com",
  "password": "admin123",
  "mfa_code": "123456"  // Optional, required if MFA enabled
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "email": "admin@example.com",
      "roles": ["admin"],
      "permissions": ["users:read", "users:create", ...],
      "mfa_enabled": false,
      "auth_method": "local"
    },
    "requires_mfa": false
  }
}

Logout

POST /auth/logout
Authorization: Bearer <token>

Refresh Token

POST /auth/refresh
Authorization: Bearer <token>

Get Current User

GET /auth/me
Authorization: Bearer <token>

SSO/OIDC Endpoints

List SSO Providers

GET /auth/sso/providers

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Azure AD",
      "provider_type": "oidc",
      "issuer_url": "https://login.microsoftonline.com/{tenant}/v2.0",
      "scopes": ["openid", "email", "profile"],
      "is_active": true,
      "is_default": true
    }
  ]
}

Initiate SSO Login

POST /auth/sso/login/:provider_id

Response:

{
  "success": true,
  "data": {
    "authorization_url": "https://login.microsoftonline.com/...",
    "state": "random-state-string"
  }
}

SSO Callback

POST /auth/sso/callback/:provider_id
Content-Type: application/json

{
  "code": "authorization-code-from-idp"
}

MFA Endpoints

Setup MFA

POST /auth/mfa/setup
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code_uri": "otpauth://totp/EdgeAI:user@example.com?secret=...",
    "backup_codes": ["A1B2C3D4", "E5F6G7H8", ...]
  }
}

Enable MFA

POST /auth/mfa/enable
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "123456"
}

Disable MFA

POST /auth/mfa/disable
Authorization: Bearer <token>

User Management Endpoints

List Users

GET /users
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "roles": ["analyst"],
      "permissions": ["incidents:read", "summaries:read"],
      "mfa_enabled": true,
      "auth_method": "local",
      "created_at": "2026-02-23T00:00:00Z",
      "last_login": "2026-02-23T12:00:00Z"
    }
  ]
}

Create User

POST /users
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "newuser@example.com",
  "password": "securepassword",
  "role": "analyst"
}

Get User

GET /users/:id
Authorization: Bearer <token>

Delete User

DELETE /users/:id
Authorization: Bearer <token>

Assign Role to User

POST /users/:id/roles
Authorization: Bearer <token>
Content-Type: application/json

{
  "role_id": "uuid"
}

Remove Role from User

DELETE /users/:id/roles/:role_id
Authorization: Bearer <token>

Role Management Endpoints

List Roles

GET /roles
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "admin",
      "description": "Full system access",
      "is_system": true
    },
    {
      "id": "uuid",
      "name": "analyst",
      "description": "View and analyze data",
      "is_system": true
    }
  ]
}

Create Role

POST /roles
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "security_engineer",
  "description": "Manage alerts and correlation rules"
}

Get Role

GET /roles/:id
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "admin",
    "description": "Full system access",
    "is_system": true,
    "permissions": [
      {
        "id": "uuid",
        "resource": "users",
        "action": "read",
        "description": "View user information"
      }
    ]
  }
}

Delete Role

DELETE /roles/:id
Authorization: Bearer <token>

Get Role Permissions

GET /roles/:id/permissions
Authorization: Bearer <token>

Assign Permission to Role

POST /roles/:id/permissions
Authorization: Bearer <token>
Content-Type: application/json

{
  "permission_id": "uuid"
}

Alerting Endpoints

List Alert Rules

GET /alerting/rules
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": [
    {
      "rule": {
        "id": "uuid",
        "name": "High Risk Alert",
        "description": "Alert when risk score exceeds threshold",
        "is_active": true,
        "condition_type": "risk_score_threshold",
        "risk_score_min": 70,
        "cooldown_minutes": 60,
        "max_alerts_per_hour": 10
      },
      "channels": [
        {
          "id": "uuid",
          "name": "Security Team Slack",
          "channel_type": "slack"
        }
      ]
    }
  ]
}

Create Alert Rule

POST /alerting/rules
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Critical Risk Alert",
  "description": "Alert on critical risk scores",
  "condition_type": "risk_score_threshold",
  "condition_config": {},
  "risk_score_min": 80,
  "severity_threshold": "critical",
  "cooldown_minutes": 30,
  "max_alerts_per_hour": 5,
  "schedule_enabled": false,
  "schedule_config": {},
  "channel_ids": ["uuid-1", "uuid-2"]
}

Get Alert Rule

GET /alerting/rules/:id
Authorization: Bearer <token>

Delete Alert Rule

DELETE /alerting/rules/:id
Authorization: Bearer <token>

Toggle Alert Rule

POST /alerting/rules/:id/toggle
Authorization: Bearer <token>

List Alert Channels

GET /alerting/channels
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Security Email",
      "channel_type": "email",
      "config": {
        "recipients": ["security@example.com"],
        "smtp_server": "smtp.gmail.com"
      },
      "is_active": true
    }
  ]
}

Create Alert Channel

POST /alerting/channels
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Slack Webhook",
  "channel_type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/..."
  }
}

Test Alert Channel

POST /alerting/channels/:id/test
Authorization: Bearer <token>

List Alerts

GET /alerting/alerts?status=fired&limit=50
Authorization: Bearer <token>

Query parameters:

  • status (optional): fired, acknowledged, resolved
  • limit (optional): Number of results (default: 100)

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "alert_rule_id": "uuid",
      "incident_id": "uuid",
      "status": "fired",
      "severity": "high",
      "title": "High Risk Score Detected",
      "description": "Identity user123 has risk score of 85",
      "context_data": {},
      "created_at": "2026-02-23T12:00:00Z"
    }
  ]
}

Acknowledge Alert

POST /alerting/alerts/:id/acknowledge
Authorization: Bearer <token>

Resolve Alert

POST /alerting/alerts/:id/resolve
Authorization: Bearer <token>

Audit Log Endpoints

Query Audit Logs

GET /audit/logs?action=login&limit=100
Authorization: Bearer <token>

Query parameters:

  • user_id (optional): Filter by user UUID
  • action (optional): Filter by action type
  • resource_type (optional): Filter by resource
  • start_time (optional): ISO 8601 timestamp
  • end_time (optional): ISO 8601 timestamp
  • limit (optional): Number of results (default: 100)
  • offset (optional): Pagination offset

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "timestamp": "2026-02-23T12:00:00Z",
      "user_email": "admin@example.com",
      "action": "login",
      "resource_type": "auth",
      "resource_id": null,
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "request_method": "POST",
      "request_path": "/api/v1/auth/login",
      "response_status": 200,
      "integrity_hash": "abc123..."
    }
  ]
}

Get Audit Statistics

GET /audit/stats?start_time=2026-02-01T00:00:00Z&end_time=2026-02-23T23:59:59Z
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "total_count": 15000,
    "action_counts": [
      ["login", 5000],
      ["view_incident", 3000],
      ["update_incident", 1500]
    ],
    "resource_counts": [
      ["auth", 5000],
      ["incidents", 4500],
      ["summaries", 3000]
    ],
    "start_time": "2026-02-01T00:00:00Z",
    "end_time": "2026-02-23T23:59:59Z"
  }
}

Export Audit Logs

GET /audit/export?format=json
Authorization: Bearer <token>

Query parameters:

  • format (required): json or csv
  • start_time (optional): ISO 8601 timestamp
  • end_time (optional): ISO 8601 timestamp

Response:

{
  "success": true,
  "data": "[JSON or CSV content as string]"
}

Dashboard Endpoints

Get Dashboard Metrics

GET /dashboard/metrics
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "summaries_received": 1000,
    "anomalies_received": 50,
    "incidents_created": 10,
    "data_reduction_percent": 99.0,
    "active_agents": 5
  }
}

Get Summaries

GET /dashboard/summaries
Authorization: Bearer <token>

Get Incidents

GET /dashboard/incidents
Authorization: Bearer <token>

Incident Endpoints

List Incidents

GET /incidents?status=open&limit=50
Authorization: Bearer <token>

Get Incident

GET /incidents/:id
Authorization: Bearer <token>

Graph Endpoints

List Nodes

GET /graph/nodes
Authorization: Bearer <token>

List Edges

GET /graph/edges
Authorization: Bearer <token>

Blast Radius

GET /graph/blast-radius/:node_id
Authorization: Bearer <token>

Health Check Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "0.2.0"
}

Readiness Check

GET /ready

Response:

{
  "status": "ready",
  "checks": {
    "database": "connected",
    "grpc": "listening"
  }
}

Error Responses

All errors follow this format:

{
  "success": false,
  "data": null,
  "error": "Error message description"
}

HTTP Status Codes

Code Meaning
200 Success
201 Created
400 Bad Request
401 Unauthorized - Invalid or missing token
403 Forbidden - Insufficient permissions
404 Not Found
422 Validation Error
500 Internal Server Error
502 Bad Gateway - SSO provider error

Permission Reference

Resources and actions for RBAC:

Resource Actions
users read, create, update, delete
roles read, create, update, delete
incidents read, create, update, delete
summaries read
alerts read, create, update, delete
alert_rules read, create, update, delete
alert_channels read, create, update, delete
settings read, update
audit_logs read

Example permission: users:read, alerts:create

Rate Limiting

API endpoints are subject to rate limiting:

  • Authentication endpoints: 10 requests per minute
  • Other endpoints: 1000 requests per minute per user

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

API Version: 0.2.0
Last Updated: 2026-02-23