trustos/docs/API.md

# TrustOS API Documentation

This document provides comprehensive API reference documentation for the TrustOS backend API.

---

## Table of Contents

- [Overview](#overview)
- [Authentication](#authentication)
- [Base URL](#base-url)
- [Response Format](#response-format)
- [Error Handling](#error-handling)
- [Rate Limiting](#rate-limiting)
- [API Endpoints](#api-endpoints)
  - [Authentication](#authentication-endpoints)
  - [Dashboard](#dashboard-endpoints)
  - [Findings](#findings-endpoints)
  - [Audit Reports](#audit-reports-endpoints)
  - [Attack Paths](#attack-paths-endpoints)
  - [Digital Footprint](#digital-footprint-endpoints)
  - [AI Services](#ai-services-endpoints)
- [Data Models](#data-models)
- [Examples](#examples)

---

## Overview

The TrustOS API is a RESTful API built with FastAPI that provides programmatic access to all TrustOS features. The API uses JSON for request and response bodies and follows standard HTTP methods and status codes.

### Key Features

- **JWT Authentication**: Secure token-based authentication
- **Multi-Tenant**: All endpoints require tenant context
- **Role-Based Access**: Different permissions for different user roles
- **Async I/O**: High-performance async operations
- **OpenAPI/Swagger**: Interactive API documentation at `/docs`

---

## Authentication

### Obtaining an Access Token

To access protected endpoints, you must first authenticate and obtain a JWT token.

**Endpoint**: `POST /api/v1/auth/login`

**Request Body**:
```json
{
  "email": "user@example.com",
  "password": "your-password"
}
```

**Response**:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "role": "executive",
  "tenant_id": "uuid-here",
  "full_name": "John Doe"
}
```

### Using the Token

Include the token in the `Authorization` header for all protected requests:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Token Expiration

- Access tokens expire after 8 hours (configurable via `ACCESS_TOKEN_EXPIRE_MINUTES`)
- After expiration, you must re-authenticate to obtain a new token

### Getting Current User Info

**Endpoint**: `GET /api/v1/auth/me`

**Headers**: `Authorization: Bearer <token>`

**Response**:
```json
{
  "id": "user-uuid",
  "email": "user@example.com",
  "full_name": "John Doe",
  "role": "executive",
  "tenant_id": "tenant-uuid"
}
```

---

## Base URL

### Development
```
http://localhost:8000/api/v1
```

### Production
```
https://api.trustos.com/api/v1
```

---

## Response Format

### Success Response

```json
{
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "uuid-here"
  }
}
```

### Error Response

```json
{
  "detail": "Error message describing what went wrong"
}
```

---

## Error Handling

### HTTP Status Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid input data |
| 401 | Unauthorized - Missing or invalid token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource does not exist |
| 422 | Validation Error - Request validation failed |
| 500 | Internal Server Error - Server error |

### Common Errors

#### 401 Unauthorized
```json
{
  "detail": "Could not validate credentials"
}
```
**Solution**: Check that your token is valid and not expired.

#### 403 Forbidden
```json
{
  "detail": "Access denied"
}
```
**Solution**: Check that your role has permission for this endpoint.

#### 404 Not Found
```json
{
  "detail": "Finding not found"
}
```
**Solution**: Verify the resource ID is correct.

---

## Rate Limiting

Rate limiting is planned for future implementation. Currently, there are no rate limits on API endpoints.

---

## API Endpoints

### Authentication Endpoints

#### Login

Authenticate a user and receive an access token.

```
POST /api/v1/auth/login
```

**Request Body**:
```json
{
  "email": "string",
  "password": "string"
}
```

**Response** (200):
```json
{
  "access_token": "string",
  "token_type": "bearer",
  "role": "executive|it_admin|trustos_admin",
  "tenant_id": "string",
  "full_name": "string"
}
```

**Permissions**: Public (no authentication required)

---

#### Get Current User

Get information about the authenticated user.

```
GET /api/v1/auth/me
```

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "id": "string",
  "email": "string",
  "full_name": "string",
  "role": "executive|it_admin|trustos_admin",
  "tenant_id": "string"
}
```

**Permissions**: Any authenticated user

---

### Dashboard Endpoints

#### Get Dashboard Data

Retrieve dashboard data including risk scores, trends, and top risks.

```
GET /api/v1/dashboard?tenant_id={tenant_id}
```

**Query Parameters**:
- `tenant_id` (required): UUID of the tenant

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "tenant_name": "Acme Corp",
  "current_score": 78.5,
  "previous_score": 75.0,
  "score_delta": 3.5,
  "score_trend": [
    {"date": "2024-01-01", "score": 70.0},
    {"date": "2024-01-02", "score": 72.0},
    ...
  ],
  "top_risks": [
    {
      "id": "finding-uuid",
      "title": "Critical SQL Injection Vulnerability",
      "ai_summary": "An attacker could access your database...",
      "ai_business_impact": "Customer data exposure, regulatory fines",
      "ai_impact_level": "High",
      "ai_fix_priority": "urgent",
      "severity": "critical",
      "category": "web_application"
    }
  ],
  "open_critical": 2,
  "open_high": 5,
  "open_medium": 12,
  "total_open": 19,
  "baseline_score": 65.0,
  "baseline_date": "2024-01-01T00:00:00Z"
}
```

**Permissions**: Executive, IT Admin, TrustOS Admin

**Tenant Isolation**: Users can only access their own tenant's data (except TrustOS Admin)

---

### Findings Endpoints

#### List Findings

Retrieve a paginated list of findings with optional filtering.

```
GET /api/v1/findings?tenant_id={tenant_id}&severity={severity}&status={status}&category={category}&limit={limit}&offset={offset}
```

**Query Parameters**:
- `tenant_id` (required): UUID of the tenant
- `severity` (optional): Filter by severity (critical, high, medium, low, info)
- `status` (optional): Filter by status (open, in_progress, resolved, verified)
- `category` (optional): Filter by category
- `limit` (optional): Maximum number of results (default: 50)
- `offset` (optional): Number of results to skip (default: 0)

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
[
  {
    "id": "finding-uuid",
    "tenant_id": "tenant-uuid",
    "asset_id": "asset-uuid",
    "title": "Critical SQL Injection Vulnerability",
    "severity": "critical",
    "status": "open",
    "category": "web_application",
    "technical_description": "SQL injection vulnerability in login form...",
    "cve_id": "CVE-2024-1234",
    "cvss_score": 9.8,
    "affected_component": "login-form",
    "ai_summary": "An attacker could access your database...",
    "ai_business_impact": "Customer data exposure, regulatory fines",
    "ai_impact_level": "High",
    "ai_remediation_steps": "1. Use parameterized queries\n2. Implement input validation...",
    "ai_fix_priority": "urgent",
    "assignee_email": "it@example.com",
    "due_date": "2024-01-15T00:00:00Z",
    "is_top_risk": true,
    "source": "manual",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]
```

**Permissions**: Executive, IT Admin, TrustOS Admin

---

#### Get Finding Detail

Retrieve detailed information about a specific finding.

```
GET /api/v1/findings/{finding_id}
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "id": "finding-uuid",
  "tenant_id": "tenant-uuid",
  "asset_id": "asset-uuid",
  "title": "Critical SQL Injection Vulnerability",
  "severity": "critical",
  "status": "open",
  "category": "web_application",
  "technical_description": "SQL injection vulnerability in login form...",
  "cve_id": "CVE-2024-1234",
  "cvss_score": 9.8,
  "affected_component": "login-form",
  "evidence": "PoC exploit code...",
  "ai_summary": "An attacker could access your database...",
  "ai_business_impact": "Customer data exposure, regulatory fines",
  "ai_impact_level": "High",
  "ai_remediation_steps": "1. Use parameterized queries\n2. Implement input validation...",
  "ai_fix_priority": "urgent",
  "assignee_email": "it@example.com",
  "due_date": "2024-01-15T00:00:00Z",
  "resolution_note": null,
  "resolved_at": null,
  "verified_at": null,
  "is_top_risk": true,
  "source": "manual",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

**Permissions**: Executive, IT Admin, TrustOS Admin

---

#### Create Finding

Create a new finding (IT Admin and TrustOS Admin only).

```
POST /api/v1/findings?tenant_id={tenant_id}
```

**Query Parameters**:
- `tenant_id` (required): UUID of the tenant

**Request Body**:
```json
{
  "title": "Critical SQL Injection Vulnerability",
  "severity": "critical",
  "category": "web_application",
  "technical_description": "SQL injection vulnerability in login form...",
  "cve_id": "CVE-2024-1234",
  "cvss_score": 9.8,
  "affected_component": "login-form",
  "asset_id": "asset-uuid",
  "executive_id": "executive-uuid",
  "source": "manual"
}
```

**Response** (201):
```json
{
  "id": "finding-uuid",
  "tenant_id": "tenant-uuid",
  "title": "Critical SQL Injection Vulnerability",
  "severity": "critical",
  "status": "open",
  "category": "web_application",
  ...
}
```

**Permissions**: IT Admin, TrustOS Admin

---

#### Update Finding Status

Update the status of a finding with optional resolution details.

```
PATCH /api/v1/findings/{finding_id}/status
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Request Body**:
```json
{
  "status": "resolved",
  "resolution_note": "Fixed by implementing parameterized queries",
  "assignee_email": "it@example.com",
  "due_date": "2024-01-15T00:00:00Z"
}
```

**Response** (200):
```json
{
  "id": "finding-uuid",
  "status": "resolved",
  "resolution_note": "Fixed by implementing parameterized queries",
  "resolved_at": "2024-01-10T00:00:00Z",
  ...
}
```

**Permissions**: IT Admin, TrustOS Admin

**Note**: When status changes to `verified`, a `resolution_note` is required.

---

#### Toggle Top Risk

Mark or unmark a finding as a top risk.

```
PATCH /api/v1/findings/{finding_id}/top-risk?is_top_risk={true|false}
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Query Parameters**:
- `is_top_risk` (required): Boolean value

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "id": "finding-uuid",
  "is_top_risk": true,
  ...
}
```

**Permissions**: IT Admin, TrustOS Admin

---

### Audit Reports Endpoints

#### List Audit Reports

Retrieve a list of audit reports for a tenant.

```
GET /api/v1/audit-reports?tenant_id={tenant_id}
```

**Query Parameters**:
- `tenant_id` (required): UUID of the tenant

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
[
  {
    "id": "report-uuid",
    "tenant_id": "tenant-uuid",
    "title": "Q1 2024 Vault Audit Report",
    "report_date": "2024-01-15T00:00:00Z",
    "baseline_score": 65.0,
    "executive_summary": "Overall security posture improved...",
    "scope_description": "All production systems and cloud infrastructure",
    "pdf_path": "/app/storage/reports/vault-audit-report-uuid.pdf",
    "is_baseline": true,
    "generated_by": "admin@trustos.com",
    "created_at": "2024-01-15T00:00:00Z"
  }
]
```

**Permissions**: TrustOS Admin only

---

#### Generate Audit Report

Generate a new Vault Audit Report for a tenant.

```
POST /api/v1/audit-reports/generate?tenant_id={tenant_id}
```

**Query Parameters**:
- `tenant_id` (required): UUID of the tenant

**Request Body**:
```json
{
  "title": "Q1 2024 Vault Audit Report",
  "executive_summary": "Overall security posture improved by 15%...",
  "scope_description": "All production systems and cloud infrastructure"
}
```

**Response** (201):
```json
{
  "id": "report-uuid",
  "tenant_id": "tenant-uuid",
  "title": "Q1 2024 Vault Audit Report",
  "report_date": "2024-01-15T00:00:00Z",
  "baseline_score": 65.0,
  "executive_summary": "Overall security posture improved by 15%...",
  "scope_description": "All production systems and cloud infrastructure",
  "pdf_path": null,
  "is_baseline": true,
  "generated_by": "admin@trustos.com",
  "created_at": "2024-01-15T00:00:00Z"
}
```

**Permissions**: TrustOS Admin only

**Note**: PDF generation happens asynchronously in the background.

---

#### Get Audit Report Detail

Retrieve detailed information about a specific audit report.

```
GET /api/v1/audit-reports/{report_id}
```

**Path Parameters**:
- `report_id` (required): UUID of the report

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "id": "report-uuid",
  "tenant_id": "tenant-uuid",
  "title": "Q1 2024 Vault Audit Report",
  "report_date": "2024-01-15T00:00:00Z",
  "baseline_score": 65.0,
  "executive_summary": "Overall security posture improved by 15%...",
  "scope_description": "All production systems and cloud infrastructure",
  "pdf_path": "/app/storage/reports/vault-audit-report-uuid.pdf",
  "is_baseline": true,
  "generated_by": "admin@trustos.com",
  "created_at": "2024-01-15T00:00:00Z"
}
```

**Permissions**: TrustOS Admin only

---

### Attack Paths Endpoints

#### Get Attack Paths

Retrieve attack path visualizations for a finding.

```
GET /api/v1/attack-paths/{finding_id}
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
[
  {
    "id": "path-uuid",
    "finding_id": "finding-uuid",
    "title": "Attack path: SQL Injection to Customer Database",
    "ai_narrative": "An attacker could exploit the SQL injection vulnerability in the login form to bypass authentication, then use the compromised admin account to access the customer database directly.",
    "nodes_json": "[{\"id\":\"1\",\"label\":\"Internet\",\"type\":\"attacker\",\"risk_level\":\"none\"},{\"id\":\"2\",\"label\":\"Login Form\",\"type\":\"entry_point\",\"risk_level\":\"critical\"}]",
    "edges_json": "[{\"source\":\"1\",\"target\":\"2\"},{\"source\":\"2\",\"target\":\"3\"}]",
    "created_at": "2024-01-01T00:00:00Z"
  }
]
```

**Permissions**: Executive, IT Admin, TrustOS Admin

---

#### Generate Attack Path

Trigger AI generation of an attack path for a finding.

```
POST /api/v1/attack-paths/{finding_id}/generate
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "status": "queued",
  "finding_id": "finding-uuid"
}
```

**Permissions**: Executive, IT Admin, TrustOS Admin

**Note**: Attack path generation happens asynchronously in the background.

---

### Digital Footprint Endpoints

#### Get Digital Footprint

Retrieve digital footprint data for a tenant.

```
GET /api/v1/footprint/{tenant_id}
```

**Path Parameters**:
- `tenant_id` (required): UUID of the tenant

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "tenant_id": "tenant-uuid",
  "executives": [
    {
      "id": "executive-uuid",
      "name": "John Smith",
      "title": "CEO",
      "email": "john@acmecorp.io"
    }
  ],
  "footprint_findings": [
    {
      "id": "finding-uuid",
      "title": "Executive email exposed in breach",
      "severity": "high",
      "ai_summary": "CEO's email found in data breach...",
      "status": "open",
      "source": "hibp"
    }
  ],
  "total_exposures": 5
}
```

**Permissions**: IT Admin, TrustOS Admin

---

#### List Authorized Assets

Retrieve list of authorized assets for a tenant.

```
GET /api/v1/footprint/authorized-assets/{tenant_id}
```

**Path Parameters**:
- `tenant_id` (required): UUID of the tenant

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
[
  {
    "id": "asset-uuid",
    "tenant_id": "tenant-uuid",
    "value": "acmecorp.io",
    "asset_type": "domain",
    "description": "Primary corporate domain",
    "authorized_by": "admin@trustos.com",
    "authorized_at": "2024-01-01T00:00:00Z",
    "is_active": true
  }
]
```

**Permissions**: IT Admin, TrustOS Admin

---

#### Add Authorized Asset

Add a new authorized asset for monitoring.

```
POST /api/v1/footprint/authorized-assets/{tenant_id}
```

**Path Parameters**:
- `tenant_id` (required): UUID of the tenant

**Request Body**:
```json
{
  "value": "acmecorp.io",
  "asset_type": "domain",
  "description": "Primary corporate domain",
  "authorized_by": "admin@trustos.com"
}
```

**Response** (201):
```json
{
  "id": "asset-uuid",
  "tenant_id": "tenant-uuid",
  "value": "acmecorp.io",
  "asset_type": "domain",
  "description": "Primary corporate domain",
  "authorized_by": "admin@trustos.com",
  "authorized_at": "2024-01-01T00:00:00Z",
  "is_active": true
}
```

**Permissions**: TrustOS Admin only

---

### AI Services Endpoints

#### Translate Finding

Trigger or re-trigger AI translation for a finding.

```
POST /api/v1/ai/translate/{finding_id}
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "status": "queued",
  "finding_id": "finding-uuid"
}
```

**Permissions**: IT Admin, TrustOS Admin

**Note**: AI translation happens asynchronously in the background.

---

#### Explain Finding (AI Security Coach)

Ask an AI question about a specific finding.

```
GET /api/v1/ai/explain/{finding_id}?question={question}
```

**Path Parameters**:
- `finding_id` (required): UUID of the finding

**Query Parameters**:
- `question` (optional): Question to ask (default: "Why does this matter to our business?")

**Headers**: `Authorization: Bearer <token>`

**Response** (200):
```json
{
  "question": "Why does this matter to our business?",
  "answer": "This SQL injection vulnerability could allow attackers to access your customer database, leading to data theft, regulatory fines, and reputational damage.",
  "finding_id": "finding-uuid"
}
```

**Permissions**: IT Admin, TrustOS Admin

---

## Data Models

### User Roles

| Role | Value | Description |
|------|------|-------------|
| Executive | `executive` | View-only access to dashboard and AI summaries |
| IT Admin | `it_admin` | Full access to findings, technical details, remediation |
| TrustOS Admin | `trustos_admin` | Full access to all tenants and system configuration |

### Finding Severity

| Severity | Value | Description |
|----------|-------|-------------|
| Critical | `critical` | Immediate action required |
| High | `high` | Urgent attention needed |
| Medium | `medium` | Should be addressed soon |
| Low | `low` | Address when possible |
| Info | `info` | Informational only |

### Finding Status

| Status | Value | Description |
|--------|-------|-------------|
| Open | `open` | New finding, not yet addressed |
| In Progress | `in_progress` | Remediation in progress |
| Resolved | `resolved` | Fix implemented, awaiting verification |
| Verified | `verified` | Fix verified and confirmed |

### Finding Category

| Category | Value | Description |
|----------|-------|-------------|
| External Exposure | `external_exposure` | Exposed services to internet |
| Cloud Posture | `cloud_posture` | Cloud misconfigurations |
| Credential Exposure | `credential_exposure` | Leaked credentials |
| Digital Footprint | `digital_footprint` | OSINT findings |
| Web Application | `web_application` | Web vulnerabilities |
| Network | `network` | Network security issues |
| Identity | `identity` | Identity and access issues |
| Third Party | `third_party` | Third-party risks |
| Compliance | `compliance` | Compliance violations |
| Other | `other` | Other categories |

### Asset Type

| Type | Value | Description |
|------|-------|-------------|
| Domain | `domain` | Domain name |
| IP Address | `ip` | IP address |
| Email | `email` | Email address |
| Cloud Resource | `cloud` | Cloud infrastructure |
| Executive | `executive` | Executive profile |
| Other | `other` | Other asset types |

---

## Examples

### Python Example

```python
import requests

# Login
response = requests.post(
    "http://localhost:8000/api/v1/auth/login",
    json={"email": "executive@acmecorp.io", "password": "TrustOS2024!"}
)
token = response.json()["access_token"]

# Get dashboard
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(
    "http://localhost:8000/api/v1/dashboard?tenant_id=acme-corp-demo-001",
    headers=headers
)
dashboard_data = response.json()
print(f"Current Score: {dashboard_data['current_score']}")
```

### JavaScript Example

```javascript
// Login
const loginResponse = await fetch('http://localhost:8000/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'executive@acmecorp.io',
    password: 'TrustOS2024!'
  })
});
const { access_token } = await loginResponse.json();

// Get dashboard
const dashboardResponse = await fetch(
  'http://localhost:8000/api/v1/dashboard?tenant_id=acme-corp-demo-001',
  {
    headers: { 'Authorization': `Bearer ${access_token}` }
  }
);
const dashboardData = await dashboardResponse.json();
console.log(`Current Score: ${dashboardData.current_score}`);
```

### cURL Example

```bash
# Login
TOKEN=$(curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"executive@acmecorp.io","password":"TrustOS2024!"}' \
  | jq -r '.access_token')

# Get dashboard
curl -X GET "http://localhost:8000/api/v1/dashboard?tenant_id=acme-corp-demo-001" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Interactive Documentation

When the backend is running, interactive API documentation is available:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

These interfaces allow you to explore the API, test endpoints, and view request/response examples directly in your browser.

---

## SDKs

Official SDKs are planned for future release:

- Python SDK
- JavaScript/TypeScript SDK
- Go SDK

For now, use the REST API directly with HTTP clients.

---

## Changelog

### Version 1.0.0 (Current)
- Initial API release
- Authentication endpoints
- Dashboard endpoints
- Findings CRUD operations
- Audit report generation
- Attack path visualization
- Digital footprint management
- AI translation and coaching

---

## Support

For API support or questions:

- **Email**: api-support@trustos.com
- **Documentation**: https://docs.trustos.com
- **Status Page**: https://status.trustos.com