trustos/docs/API.md

TrustOS API Documentation

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

---

Table of Contents

• Overview
• Authentication
• Base URL
• Response Format
• Error Handling
• Rate Limiting
• API Endpoints
  • Authentication
  • Dashboard
  • Findings
  • Audit Reports
  • Attack Paths
  • Digital Footprint
  • AI Services
• Data Models
• 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:

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "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:

{
  "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

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

Error Response

{
  "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

{
  "detail": "Could not validate credentials"
}

Solution: Check that your token is valid and not expired.

403 Forbidden

{
  "detail": "Access denied"
}

Solution: Check that your role has permission for this endpoint.

404 Not Found

{
  "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:

{
  "email": "string",
  "password": "string"
}

Response (200):

{
  "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):

{
  "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):

{
  "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):

[
  {
    "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):

{
  "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:

{
  "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):

{
  "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:

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

Response (200):

{
  "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):

{
  "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):

[
  {
    "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:

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

Response (201):

{
  "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):

{
  "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):

[
  {
    "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):

{
  "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):

{
  "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):

[
  {
    "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:

{
  "value": "acmecorp.io",
  "asset_type": "domain",
  "description": "Primary corporate domain",
  "authorized_by": "admin@trustos.com"
}

Response (201):

{
  "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):

{
  "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):

{
  "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

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

// 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

# 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