Skip to content

api.md

Latest commit

 

History

History
1988 lines (1609 loc) · 49.3 KB

api.md

File metadata and controls

1988 lines (1609 loc) · 49.3 KB

Cloud Access Visualizer - Complete API Endpoints Documentation

This document provides a comprehensive list of all API endpoints available in the Cloud Access Visualizer application, including HTTP methods, descriptions, sample curl queries, and expected responses.

Base URL: http://localhost:8001 API Prefix: All endpoints use /api prefix unless specified otherwise

Table of Contents

  1. Health & System
  2. Authentication & User Management
  3. Cloud Provider Integrations
  4. Risk Analysis
  5. Compliance Frameworks
  6. Attack Surface Analysis
  7. DNS Security
  8. Group Management
  9. Analytics & Dashboard
  10. Data Export & Import
  11. Notifications
  12. Debug & Development

Health & System

GET /api/health

Description: Check API health status and CORS configuration.

Sample curl:

curl -X GET "http://localhost:8001/api/health"

Expected Response:

{
  "status": "healthy",
  "message": "Cloud Access Visualizer API is running",
  "cors": "enabled",
  "timestamp": "2024-06-01T15:00:00Z"
}

GET /docs

Description: Swagger UI documentation interface.

Sample curl:

curl -X GET "http://localhost:8001/docs"

Authentication & User Management

POST /api/auth/signup

Description: Register a new user account.

Sample curl:

curl -X POST "http://localhost:8001/api/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "full_name": "John Doe"
  }'

Expected Response:

{
  "message": "User created successfully",
  "user_id": "user_123",
  "email": "user@example.com"
}

POST /api/auth/login

Description: Authenticate user and receive JWT token.

Sample curl:

curl -X POST "http://localhost:8001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Expected Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": "user123",
    "email": "user@example.com",
    "role": "user"
  }
}

GET /api/auth/me

Description: Get current authenticated user information.

Sample curl:

curl -X GET "http://localhost:8001/api/auth/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/auth/logout

Description: Logout and invalidate current session.

Sample curl:

curl -X POST "http://localhost:8001/api/auth/logout" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/auth/sessions

Description: Get all active user sessions.

Sample curl:

curl -X GET "http://localhost:8001/api/auth/sessions" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

DELETE /api/auth/sessions/{session_id}

Description: Terminate a specific session.

Sample curl:

curl -X DELETE "http://localhost:8001/api/auth/sessions/session_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

DELETE /api/auth/sessions

Description: Terminate all user sessions.

Sample curl:

curl -X DELETE "http://localhost:8001/api/auth/sessions" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/auth/security-events

Description: Get user security events and audit logs.

Sample curl:

curl -X GET "http://localhost:8001/api/auth/security-events" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/auth/security-stats

Description: Get security statistics for the current user.

Sample curl:

curl -X GET "http://localhost:8001/api/auth/security-stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/auth/security-events

Description: Log a security event.

Sample curl:

curl -X POST "http://localhost:8001/api/auth/security-events" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "login_attempt",
    "severity": "medium",
    "description": "Failed login attempt from unusual location"
  }'

PUT /api/auth/update-profile

Description: Update user profile information.

Sample curl:

curl -X PUT "http://localhost:8001/api/auth/update-profile" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "John Smith",
    "department": "Security"
  }'

POST /api/users

Description: Create a new user (Admin only).

Sample curl:

curl -X POST "http://localhost:8001/api/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@company.com",
    "password": "SecurePass123!",
    "full_name": "New User",
    "role": "user"
  }'

GET /api/users/all

Description: Get all users with pagination.

Sample curl:

curl -X GET "http://localhost:8001/api/users/all?skip=0&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PUT /api/users/{user_id}

Description: Update user information.

Sample curl:

curl -X PUT "http://localhost:8001/api/users/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Updated Name",
    "department": "Engineering"
  }'

DELETE /api/users/{user_id}

Description: Delete a user account.

Sample curl:

curl -X DELETE "http://localhost:8001/api/users/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Cloud Provider Integrations

POST /api/integrations/create

Description: Create a new cloud provider integration.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/create" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "name": "Production AWS",
    "credentials": {
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "us-east-1"
    }
  }'

GET /api/integrations/list

Description: List all configured integrations.

Sample curl:

curl -X GET "http://localhost:8001/api/integrations/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

DELETE /api/integrations/{integration_id}

Description: Delete an integration.

Sample curl:

curl -X DELETE "http://localhost:8001/api/integrations/integration_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/integrations/discover/aws

Description: Discover AWS accounts and resources.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/discover/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }'

POST /api/integrations/discover/gcp

Description: Discover GCP projects and resources.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/discover/gcp" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_key": "base64_encoded_key",
    "project_id": "my-gcp-project"
  }'

POST /api/integrations/discover/azure

Description: Discover Azure resources and subscriptions.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/discover/azure" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "azure_client_id",
    "client_secret": "azure_client_secret",
    "tenant_id": "azure_tenant_id",
    "subscription_id": "azure_subscription_id"
  }'

GET /api/integrations/permissions/{provider}

Description: Get required permissions for a provider integration.

Sample curl:

curl -X GET "http://localhost:8001/api/integrations/permissions/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/integrations/aws/test-connection

Description: Test AWS integration connectivity.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/aws/test-connection" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }'

POST /api/integrations/azure/test-connection

Description: Test Azure integration connectivity.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/azure/test-connection" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "azure_client_id",
    "client_secret": "azure_client_secret",
    "tenant_id": "azure_tenant_id"
  }'

POST /api/integrations/github/test-connection

Description: Test GitHub integration connectivity.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/github/test-connection" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personal_access_token": "github_pat_token"
  }'

POST /api/integrations/gcp/test-connection

Description: Test GCP integration connectivity.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/gcp/test-connection" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_key": "base64_encoded_key",
    "project_id": "my-gcp-project"
  }'

POST /api/integrations/okta/test-connection

Description: Test Okta integration connectivity.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/okta/test-connection" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "dev-123456.okta.com",
    "api_token": "okta_api_token"
  }'

Data Synchronization

POST /api/integrations/aws/sync

Description: Trigger AWS data synchronization.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/aws/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }'

POST /api/integrations/github/sync

Description: Trigger GitHub data synchronization.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/github/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personal_access_token": "github_pat_token"
  }'

POST /api/integrations/gcp/sync

Description: Trigger GCP data synchronization.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/gcp/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_key": "base64_encoded_key",
    "project_id": "my-gcp-project"
  }'

POST /api/integrations/azure/sync

Description: Trigger Azure data synchronization.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/azure/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "azure_client_id",
    "client_secret": "azure_client_secret",
    "tenant_id": "azure_tenant_id",
    "subscription_id": "azure_subscription_id"
  }'

POST /api/integrations/okta/sync

Description: Trigger Okta data synchronization.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/okta/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "dev-123456.okta.com",
    "api_token": "okta_api_token"
  }'

GET /api/integrations/sync-status

Description: Get synchronization status for all providers.

Sample curl:

curl -X GET "http://localhost:8001/api/integrations/sync-status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/integrations/process-synced-data

Description: Process and analyze synced data.

Sample curl:

curl -X POST "http://localhost:8001/api/integrations/process-synced-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Risk Analysis

GET /api/risk-analysis/{user_email}

Description: Get detailed risk analysis for a specific user.

Sample curl:

curl -X GET "http://localhost:8001/api/risk-analysis/john.doe@company.com" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

{
  "user_email": "john.doe@company.com",
  "overall_risk_score": 75.5,
  "risk_category": "High",
  "risk_factors": [
    "Administrative privileges across multiple cloud providers",
    "Access to sensitive production resources",
    "Potential privilege escalation paths identified"
  ],
  "recommendations": [
    "Implement just-in-time access controls",
    "Regular access reviews",
    "Enable MFA for all privileged accounts"
  ],
  "detailed_analysis": {
    "aws": {"risk_score": 80, "privilege_level": "admin"},
    "github": {"risk_score": 70, "privilege_level": "maintainer"}
  }
}

POST /api/aws-risk-analysis/test-detailed-algorithm

Description: Test AWS risk analysis algorithm with sample data.

Sample curl:

curl -X POST "http://localhost:8001/api/aws-risk-analysis/test-detailed-algorithm" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test-user",
    "aws_credentials": {
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "us-east-1"
    }
  }'

POST /api/github-risk-analysis/test-algorithm

Description: Test GitHub risk analysis algorithm.

Sample curl:

curl -X POST "http://localhost:8001/api/github-risk-analysis/test-algorithm" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test-user",
    "organization": "test-org",
    "github_token": "github_pat_token"
  }'

POST /api/azure-risk-analysis/test-algorithm

Description: Test Azure risk analysis algorithm.

Sample curl:

curl -X POST "http://localhost:8001/api/azure-risk-analysis/test-algorithm" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_principal_name": "user@company.com",
    "azure_credentials": {
      "client_id": "azure_client_id",
      "client_secret": "azure_client_secret",
      "tenant_id": "azure_tenant_id"
    }
  }'

GET /api/users/risky

Description: Get users with highest risk scores.

Sample curl:

curl -X GET "http://localhost:8001/api/users/risky?limit=10&min_risk_score=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/users/recalculate-risk-scores

Description: Trigger recalculation of risk scores for all users.

Sample curl:

curl -X POST "http://localhost:8001/api/users/recalculate-risk-scores" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/users/{user_email}/aggregated-risk

Description: Get aggregated risk analysis across all providers for a user.

Sample curl:

curl -X GET "http://localhost:8001/api/users/john.doe@company.com/aggregated-risk" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GitHub-specific Risk Analysis

GET /api/github-risk-analysis/configuration

Description: Get GitHub risk analysis configuration.

Sample curl:

curl -X GET "http://localhost:8001/api/github-risk-analysis/configuration" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/github-risk-analysis/configuration/repository-criticality

Description: Update GitHub repository criticality tiers.

Sample curl:

curl -X POST "http://localhost:8001/api/github-risk-analysis/configuration/repository-criticality" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tier_updates": {
      "Tier0_Critical": ["production-api", "core-services"],
      "Tier1_High": ["user-service", "payment-service"]
    }
  }'

POST /api/github-risk-analysis/configuration/permission-weights

Description: Update GitHub permission risk weights.

Sample curl:

curl -X POST "http://localhost:8001/api/github-risk-analysis/configuration/permission-weights" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission_weights": {
      "admin": 100,
      "maintain": 80,
      "write": 60,
      "read": 10
    }
  }'

POST /api/github-risk-analysis/configuration/scoring-weights

Description: Update GitHub scoring algorithm weights.

Sample curl:

curl -X POST "http://localhost:8001/api/github-risk-analysis/configuration/scoring-weights" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "component_weights": {
      "repository_access": 0.6,
      "organization_role": 0.3,
      "security_hygiene": 0.1
    }
  }'

GET /api/github-risk-analysis/users/{user_login}/detailed

Description: Get detailed GitHub risk analysis for a specific user.

Sample curl:

curl -X GET "http://localhost:8001/api/github-risk-analysis/users/johndoe/detailed" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/github-risk-analysis/users/summary

Description: Get summary of GitHub users risk analysis.

Sample curl:

curl -X GET "http://localhost:8001/api/github-risk-analysis/users/summary" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/github-risk-analysis/users/bulk-analyze

Description: Trigger bulk risk analysis for multiple GitHub users.

Sample curl:

curl -X POST "http://localhost:8001/api/github-risk-analysis/users/bulk-analyze" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_logins": ["user1", "user2", "user3"],
    "organization": "my-org"
  }'

GitHub API Endpoints

GET /api/github/test-token

Description: Test GitHub token validity.

Sample curl:

curl -X GET "http://localhost:8001/api/github/test-token" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/github/user

Description: Get authenticated GitHub user information.

Sample curl:

curl -X GET "http://localhost:8001/api/github/user" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/github/organizations

Description: Get GitHub organizations for authenticated user.

Sample curl:

curl -X GET "http://localhost:8001/api/github/organizations" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/github/repositories

Description: Get GitHub repositories for authenticated user.

Sample curl:

curl -X GET "http://localhost:8001/api/github/repositories?per_page=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/github/organizations/{org_name}/members

Description: Get members of a specific GitHub organization.

Sample curl:

curl -X GET "http://localhost:8001/api/github/organizations/my-org/members" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

User and Resource Management

GET /api/synced-users

Description: Get all synchronized users from cloud providers.

Sample curl:

curl -X GET "http://localhost:8001/api/synced-users?provider=aws&skip=0&limit=100" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/users

Description: Get users with filtering and pagination.

Sample curl:

curl -X GET "http://localhost:8001/api/users?provider=aws&risk_level=high&skip=0&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

{
  "users": [
    {
      "user_email": "john.doe@company.com",
      "user_name": "John Doe",
      "department": "Engineering",
      "overall_risk_score": 75.5,
      "provider": "aws",
      "access_type": "admin",
      "last_updated": "2024-06-01T10:00:00Z"
    }
  ],
  "total": 1250,
  "skip": 0,
  "limit": 50,
  "has_more": true
}

GET /api/users/paginated

Description: Get paginated users with enhanced filtering.

Sample curl:

curl -X GET "http://localhost:8001/api/users/paginated?page=1&page_size=25&search=john" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/search/{user_email}

Description: Search for a specific user by email.

Sample curl:

curl -X GET "http://localhost:8001/api/search/john.doe@company.com" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/users/{user_email}/resources

Description: Get all cloud resources accessible by a specific user.

Sample curl:

curl -X GET "http://localhost:8001/api/users/john.doe@company.com/resources" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

[
  {
    "id": "resource_123",
    "provider": "aws",
    "service": "S3",
    "resource_name": "production-data-bucket",
    "access_type": "read-write",
    "risk_level": "high",
    "last_accessed": "2024-06-01T08:30:00Z"
  }
]

DELETE /api/users/access/{user_email}

Description: Remove all access for a specific user (emergency access revocation).

Sample curl:

curl -X DELETE "http://localhost:8001/api/users/access/john.doe@company.com" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/search/resource/{resource_name}

Description: Search for resources by name.

Sample curl:

curl -X GET "http://localhost:8001/api/search/resource/production-database" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Analytics & Dashboard

GET /api/analytics/overview

Description: Get comprehensive analytics overview.

Sample curl:

curl -X GET "http://localhost:8001/api/analytics/overview" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

{
  "summary": {
    "total_users": 1250,
    "total_resources": 15600,
    "high_risk_users": 45,
    "cross_provider_admins": 12
  },
  "risk_distribution": {
    "low": 850,
    "medium": 300,
    "high": 80,
    "critical": 20
  },
  "provider_stats": {
    "aws": {"total_users": 800, "admin_users": 25},
    "github": {"total_users": 450, "admin_users": 8}
  }
}

GET /api/analytics

Description: Get detailed analytics with time-based insights.

Sample curl:

curl -X GET "http://localhost:8001/api/analytics?time_range=30d" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/analytics/dashboard/{provider}

Description: Get provider-specific dashboard analytics.

Sample curl:

curl -X GET "http://localhost:8001/api/analytics/dashboard/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/analytics/provider/{provider}

Description: Get comprehensive analytics for a specific provider.

Sample curl:

curl -X GET "http://localhost:8001/api/analytics/provider/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/dashboard/unified

Description: Get unified dashboard data across all providers.

Sample curl:

curl -X GET "http://localhost:8001/api/dashboard/unified" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Data Export & Import

GET /api/export/{format}

Description: Export user and resource data in various formats.

Sample curl:

curl -X GET "http://localhost:8001/api/export/csv?provider=aws&risk_level=high" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output export.csv

Available formats: csv, xlsx, json

POST /api/reports/generate

Description: Generate comprehensive security reports.

Sample curl:

curl -X POST "http://localhost:8001/api/reports/generate?format=pdf&company_name=Acme%20Corp" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output security_report.pdf

Available formats: pdf, html, pptx

GET /api/reports/preview

Description: Get preview data for report generation.

Sample curl:

curl -X GET "http://localhost:8001/api/reports/preview?provider=aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/import/json

Description: Import user and resource data from JSON file.

Sample curl:

curl -X POST "http://localhost:8001/api/import/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@data.json" \
  -F "provider=aws" \
  -F "overwrite=false"

Group Management

GET /api/groups/providers/summary

Description: Get summary of groups across all providers.

Sample curl:

curl -X GET "http://localhost:8001/api/groups/providers/summary" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/groups/unified/analytics

Description: Get unified group analytics across providers.

Sample curl:

curl -X GET "http://localhost:8001/api/groups/unified/analytics" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/groups/search

Description: Search for groups across providers.

Sample curl:

curl -X GET "http://localhost:8001/api/groups/search?q=admin&provider=aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/groups/export

Description: Export group data.

Sample curl:

curl -X GET "http://localhost:8001/api/groups/export?format=csv&provider=aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output groups.csv

GET /api/groups/{provider}

Description: Get groups for a specific provider.

Sample curl:

curl -X GET "http://localhost:8001/api/groups/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/groups/{provider}/{group_id}/details

Description: Get detailed information about a specific group.

Sample curl:

curl -X GET "http://localhost:8001/api/groups/aws/group_123/details" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/synced-groups

Description: Get all synchronized groups.

Sample curl:

curl -X GET "http://localhost:8001/api/synced-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/synced-groups/{provider}

Description: Get synchronized groups for a specific provider.

Sample curl:

curl -X GET "http://localhost:8001/api/synced-groups/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/groups/sync

Description: Trigger group synchronization.

Sample curl:

curl -X POST "http://localhost:8001/api/groups/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "force_refresh": true
  }'

Provider-specific Group Endpoints

GET /api/providers/aws/groups

Description: Get AWS IAM groups.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/aws/groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/providers/azure/groups

Description: Get Azure AD groups.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/azure/groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/providers/gcp/groups

Description: Get GCP groups.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/gcp/groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/providers/github/groups

Description: Get GitHub teams and organizations.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/github/groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/providers/okta/groups

Description: Get Okta groups.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/okta/groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Compliance Frameworks

GET /api/compliance/frameworks

Description: Get all available compliance frameworks.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/frameworks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

{
  "frameworks": [
    {
      "id": "cis_2.0_aws",
      "name": "CIS Controls v2.0 for AWS",
      "description": "Center for Internet Security AWS benchmark",
      "total_checks": 245,
      "supported_providers": ["aws"]
    }
  ]
}

GET /api/compliance/frameworks/{framework_type}/checks

Description: Get all checks for a specific compliance framework.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/frameworks/cis_2.0_aws/checks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/compliance/frameworks/{framework_type}

Description: Get detailed information about a compliance framework.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/frameworks/cis_2.0_aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/compliance/assess/{framework_type}

Description: Run compliance assessment for a specific framework.

Sample curl:

curl -X POST "http://localhost:8001/api/compliance/assess/cis_2.0_aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aws_credentials": {
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "us-east-1"
    }
  }'

GET /api/compliance/assessments

Description: Get all compliance assessments.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/assessments?limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/compliance/assessments/{assessment_id}

Description: Get specific compliance assessment results.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/assessments/assessment_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/compliance/dashboard

Description: Get compliance dashboard summary.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/dashboard" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/compliance/export/{framework_type}

Description: Export compliance assessment results.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/export/cis_2.0_aws?format=pdf" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output compliance_report.pdf

POST /api/compliance/unified/assess

Description: Run unified compliance assessment across multiple frameworks.

Sample curl:

curl -X POST "http://localhost:8001/api/compliance/unified/assess" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "frameworks": ["cis_2.0_aws", "nist_csf_1.1_aws"],
    "aws_credentials": {
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'

GET /api/compliance/providers

Description: Get supported compliance providers.

Sample curl:

curl -X GET "http://localhost:8001/api/compliance/providers" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/compliance/assess/provider/{provider}

Description: Run compliance assessment for a specific provider.

Sample curl:

curl -X POST "http://localhost:8001/api/compliance/assess/provider/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "framework_types": ["cis_2.0_aws", "iso27001_2022_aws"],
    "credentials": {
      "access_key": "AKIAIOSFODNN7EXAMPLE",
      "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'

Attack Surface Analysis

GET /api/attack-surface/aws

Description: Get AWS attack surface analysis.

Sample curl:

curl -X GET "http://localhost:8001/api/attack-surface/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

{
  "account_id": "123456789012",
  "assessment_date": "2024-06-01T10:00:00Z",
  "risk_score": 75.5,
  "total_findings": 25,
  "summary": {
    "critical_findings": 2,
    "high_findings": 8,
    "medium_findings": 10,
    "low_findings": 5
  },
  "escalation_paths": [
    {
      "technique": "IAM_POLICY_PRIVILEGE_ESCALATION",
      "source_principal": "user:john-doe",
      "target_principal": "role:AdminRole",
      "risk_level": "high"
    }
  ]
}

GET /api/attack-surface/aws/history

Description: Get historical AWS attack surface analysis data.

Sample curl:

curl -X GET "http://localhost:8001/api/attack-surface/aws/history?days=30" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/attack-surface/aws/enhanced

Description: Get enhanced AWS attack surface analysis.

Sample curl:

curl -X GET "http://localhost:8001/api/attack-surface/aws/enhanced" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/attack-surface/gcp

Description: Get GCP attack surface analysis.

Sample curl:

curl -X GET "http://localhost:8001/api/attack-surface/gcp" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/attack-surface/gcp/history

Description: Get historical GCP attack surface analysis data.

Sample curl:

curl -X GET "http://localhost:8001/api/attack-surface/gcp/history?days=30" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/attack-surface/gcp/enhanced

Description: Get enhanced GCP attack surface analysis.

Sample curl:

curl -X GET "http://localhost:8001/api/attack-surface/gcp/enhanced" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

DNS Security

GET /api/dns-security/status

Description: Get DNS security monitoring status.

Sample curl:

curl -X GET "http://localhost:8001/api/dns-security/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/dns-security/results/aws

Description: Get AWS DNS security scan results.

Sample curl:

curl -X GET "http://localhost:8001/api/dns-security/results/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Expected Response:

{
  "scan_id": "dns_scan_123",
  "provider": "aws",
  "scan_date": "2024-06-01T10:00:00Z",
  "total_domains": 150,
  "vulnerabilities_found": 8,
  "high_risk_domains": 2,
  "findings": [
    {
      "domain": "api.company.com",
      "vulnerability_type": "DNS_HIJACKING_RISK",
      "severity": "high",
      "description": "Domain uses weak DNS configuration"
    }
  ]
}

GET /api/dns-security/results/gcp

Description: Get GCP DNS security scan results.

Sample curl:

curl -X GET "http://localhost:8001/api/dns-security/results/gcp" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/dns-security/scan/{scan_id}

Description: Get specific DNS security scan results.

Sample curl:

curl -X GET "http://localhost:8001/api/dns-security/scan/dns_scan_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/dns-security/vulnerability/{vulnerability_id}

Description: Get detailed information about a specific DNS vulnerability.

Sample curl:

curl -X GET "http://localhost:8001/api/dns-security/vulnerability/vuln_456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/dns-security/analytics/dashboard

Description: Get DNS security analytics dashboard.

Sample curl:

curl -X GET "http://localhost:8001/api/dns-security/analytics/dashboard" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Auto Analysis

POST /api/auto-analysis/trigger

Description: Trigger automated security analysis.

Sample curl:

curl -X POST "http://localhost:8001/api/auto-analysis/trigger" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "analysis_types": ["risk_assessment", "compliance_check", "attack_surface"],
    "priority": "high"
  }'

GET /api/auto-analysis/jobs

Description: Get all auto-analysis jobs and their status.

Sample curl:

curl -X GET "http://localhost:8001/api/auto-analysis/jobs" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/auto-analysis/results/{provider}/{analysis_type}

Description: Get auto-analysis results for a specific provider and type.

Sample curl:

curl -X GET "http://localhost:8001/api/auto-analysis/results/aws/risk_assessment" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/auto-analysis/status

Description: Get overall auto-analysis system status.

Sample curl:

curl -X GET "http://localhost:8001/api/auto-analysis/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Security & Best Practices

GET /api/security/recommendations/{provider}

Description: Get security recommendations for a specific provider.

Sample curl:

curl -X GET "http://localhost:8001/api/security/recommendations/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/security/credentials/setup

Description: Set up secure credential storage.

Sample curl:

curl -X POST "http://localhost:8001/api/security/credentials/setup" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "encryption_method": "aes_256",
    "key_rotation_enabled": true
  }'

GET /api/security/best-practices/{provider}

Description: Get security best practices for a provider.

Sample curl:

curl -X GET "http://localhost:8001/api/security/best-practices/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/security/dashboard

Description: Get comprehensive security dashboard.

Sample curl:

curl -X GET "http://localhost:8001/api/security/dashboard" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Credentials Management

GET /api/credentials

Description: List all configured cloud provider credentials.

Sample curl:

curl -X GET "http://localhost:8001/api/credentials" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/credentials

Description: Add new cloud provider credentials.

Sample curl:

curl -X POST "http://localhost:8001/api/credentials" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "description": "Production AWS Account",
    "credentials": {
      "access_key_id": "AKIA...",
      "secret_access_key": "xxx...",
      "region": "us-east-1"
    }
  }'

PUT /api/credentials/{credential_id}

Description: Update existing credentials.

Sample curl:

curl -X PUT "http://localhost:8001/api/credentials/cred_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated Production AWS Account",
    "credentials": {
      "region": "us-west-2"
    }
  }'

DELETE /api/credentials/{credential_id}

Description: Remove credentials.

Sample curl:

curl -X DELETE "http://localhost:8001/api/credentials/cred_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/credentials/{credential_id}/test

Description: Test credential connectivity.

Sample curl:

curl -X POST "http://localhost:8001/api/credentials/cred_123/test" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/credentials/{credential_id}/sync

Description: Trigger data synchronization using specific credentials.

Sample curl:

curl -X POST "http://localhost:8001/api/credentials/cred_123/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Sample Data & Providers

GET /api/providers/samples

Description: Get sample data for all providers.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/samples" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/providers/samples/{provider}

Description: Get sample data for a specific provider.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/samples/aws" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/providers/samples/unified/download

Description: Download unified sample data file.

Sample curl:

curl -X GET "http://localhost:8001/api/providers/samples/unified/download" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --output sample_data.json

GET /api/providers

Description: Get information about all supported cloud providers.

Sample curl:

curl -X GET "http://localhost:8001/api/providers" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Administrative Endpoints

POST /api/init-sample-data

Description: Initialize application with sample data.

Sample curl:

curl -X POST "http://localhost:8001/api/init-sample-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/create-admin

Description: Create administrative user account.

Sample curl:

curl -X POST "http://localhost:8001/api/create-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@company.com",
    "password": "SecureAdminPass123!",
    "full_name": "System Administrator"
  }'

DELETE /api/admin/clear-providers-data

Description: Clear all provider data (destructive operation).

Sample curl:

curl -X DELETE "http://localhost:8001/api/admin/clear-providers-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/audit-logs

Description: Get audit logs for system activities.

Sample curl:

curl -X GET "http://localhost:8001/api/audit-logs?limit=100&user_id=user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Notifications

The notification system is available under the /api/notifications prefix. Here are the main endpoints:

GET /api/notifications/settings/{user_id}

Description: Get user notification settings.

Sample curl:

curl -X GET "http://localhost:8001/api/notifications/settings/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PUT /api/notifications/settings/{user_id}

Description: Update user notification settings.

Sample curl:

curl -X PUT "http://localhost:8001/api/notifications/settings/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "enabled_channels": ["email", "slack"],
    "enabled_types": ["risk_alert", "compliance_violation"],
    "min_severity": "medium"
  }'

GET /api/notifications/channels/{user_id}

Description: Get user notification channels.

Sample curl:

curl -X GET "http://localhost:8001/api/notifications/channels/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/notifications/channels/{user_id}

Description: Create notification channel.

Sample curl:

curl -X POST "http://localhost:8001/api/notifications/channels/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Alerts",
    "channel_type": "email",
    "enabled": true,
    "configuration": {
      "email_address": "user@company.com"
    }
  }'

PUT /api/notifications/channels/{user_id}/{channel_id}

Description: Update notification channel.

Sample curl:

curl -X PUT "http://localhost:8001/api/notifications/channels/user_123/channel_456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Email Alerts",
    "enabled": false
  }'

DELETE /api/notifications/channels/{user_id}/{channel_id}

Description: Delete notification channel.

Sample curl:

curl -X DELETE "http://localhost:8001/api/notifications/channels/user_123/channel_456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/notifications/test/{user_id}

Description: Test notification channel.

Sample curl:

curl -X POST "http://localhost:8001/api/notifications/test/user_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_456",
    "test_message": "This is a test notification"
  }'

POST /api/notifications/send

Description: Send notification to multiple users.

Sample curl:

curl -X POST "http://localhost:8001/api/notifications/send" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_123", "user_456"],
    "notification_type": "risk_alert",
    "severity": "high",
    "title": "High Risk User Detected",
    "message": "User john.doe@company.com has been flagged as high risk"
  }'

GET /api/notifications/logs/{user_id}

Description: Get notification logs for user.

Sample curl:

curl -X GET "http://localhost:8001/api/notifications/logs/user_123?limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/notifications/test/email

Description: Test email SMTP configuration.

Sample curl:

curl -X POST "http://localhost:8001/api/notifications/test/email" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "smtp_server": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "user@gmail.com",
    "smtp_password": "app_password",
    "use_tls": true
  }'

POST /api/notifications/test/slack

Description: Test Slack webhook configuration.

Sample curl:

curl -X POST "http://localhost:8001/api/notifications/test/slack" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
  }'

POST /api/notifications/test/discord

Description: Test Discord webhook configuration.

Sample curl:

curl -X POST "http://localhost:8001/api/notifications/test/discord" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://discord.com/api/webhooks/123456789/abcdefghijklmnop"
  }'

GET /api/notifications/types

Description: Get available notification types and severities.

Sample curl:

curl -X GET "http://localhost:8001/api/notifications/types" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/notifications/templates/defaults

Description: Get default notification templates.

Sample curl:

curl -X GET "http://localhost:8001/api/notifications/templates/defaults" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/notifications/providers/smtp

Description: Get common SMTP provider configurations.

Sample curl:

curl -X GET "http://localhost:8001/api/notifications/providers/smtp" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Debug & Development

GET /api/debug/routes

Description: List all available API routes (development only).

Sample curl:

curl -X GET "http://localhost:8001/api/debug/routes" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/debug/cors

Description: Check CORS configuration.

Sample curl:

curl -X GET "http://localhost:8001/api/debug/cors" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/debug/env

Description: Get environment configuration (development only).

Sample curl:

curl -X GET "http://localhost:8001/api/debug/env" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/debug/iam-bindings

Description: Debug IAM bindings and permissions.

Sample curl:

curl -X GET "http://localhost:8001/api/debug/iam-bindings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/debug/synced-users

Description: Debug synchronized user data.

Sample curl:

curl -X GET "http://localhost:8001/api/debug/synced-users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Handling

All endpoints return consistent error responses in the following format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {},
    "timestamp": "2024-06-01T15:00:00Z",
    "request_id": "req_12345"
  }
}

Common HTTP Status Codes

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 204 No Content - Resource deleted successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource already exists
  • 422 Unprocessable Entity - Validation error
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Rate Limiting

The API implements rate limiting:

  • Authentication endpoints: 5 requests per 15 minutes per IP
  • General API endpoints: 100 requests per minute per user
  • Export endpoints: 10 requests per hour per user
  • Sync endpoints: 5 requests per hour per provider

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623456000

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

To obtain a token, use the /api/auth/login endpoint with valid credentials.

This documentation covers all available API endpoints in the Cloud Access Visualizer application. For interactive documentation, visit the Swagger UI at http://localhost:8001/docs.