GovStack API implements a comprehensive security model based on API key authentication with role-based access control. This document outlines security features, best practices, and configuration guidelines.

All API endpoints (except public health checks) require authentication via the X-API-Key header:

X-API-Key: your-secure-api-key-here

API keys are validated against a predefined set of valid keys with associated permissions:

VALID_API_KEYS = {
    "gs-master-key": {
        "name": "master",
        "permissions": ["read", "write", "delete", "admin"],
        "description": "Master API key with full access"
    },
    "gs-admin-key": {
        "name": "admin", 
        "permissions": ["read", "write", "admin"],
        "description": "Admin API key with management access"
    }
}

• Environment Variable: GOVSTACK_API_KEY
• Permissions: read, write, delete, admin (full access)
• Use Case: Full system administration, all operations
• Default Development: gs-dev-master-key-12345

• Environment Variable: GOVSTACK_ADMIN_API_KEY
• Permissions: read, write, admin (no delete)
• Use Case: Content management, audit log access
• Default Development: gs-dev-admin-key-67890

The security system provides FastAPI dependencies for permission checking:

# Permission-based dependencies
require_read_permission()    # GET operations
require_write_permission()   # POST operations  
require_delete_permission()  # DELETE operations
require_admin_permission()   # Audit logs, admin functions

• Endpoints: All GET endpoints
• Operations:
  • View documents and metadata
  • Access chat history
  • Retrieve webpage data
  • Get collection statistics
  • Check crawl status

• Endpoints: POST endpoints
• Operations:
  • Upload documents
  • Create chat messages
  • Start web crawls
  • Extract text content
  • Fetch webpages

• Endpoints: DELETE endpoints
• Operations:
  • Remove documents
  • Delete chat sessions
  • Clean up resources

• Endpoints: Admin-specific endpoints
• Operations:
  • Access audit logs
  • View system statistics
  • Administrative functions

The security system automatically logs all authenticated actions:

async def log_audit_action(
    user_id: str,
    action: str,
    resource_type: str,
    resource_id: Optional[str] = None,
    details: Optional[dict] = None,
    request: Optional[Request] = None,
    api_key_name: Optional[str] = None
):
    """Log user actions for audit trail."""

For every authenticated request, the system records:

• User ID: API key name or user identifier
• Action: Operation performed (e.g., 'upload', 'delete', 'chat')
• Resource Type: Type of resource affected (e.g., 'document', 'chat')
• Resource ID: Specific resource identifier
• IP Address: Client IP address
• User Agent: Client browser/application information
• Timestamp: When the action occurred
• Details: Additional context (e.g., file size, collection ID)

# Create audit-enabled dependency
def create_audit_dependency(action: str, resource_type: str):
    """Create dependency that requires permission and logs audit trail."""
    
    async def audit_dependency(
        request: Request,
        api_key_info: APIKeyInfo = Depends(require_permission)
    ):
        # Log the action
        await log_audit_action(
            user_id=api_key_info.name,
            action=action,
            resource_type=resource_type,
            request=request,
            api_key_name=api_key_info.name
        )
        return api_key_info
    
    return audit_dependency

# Master API key with full permissions
GOVSTACK_API_KEY="your-secure-master-key-here"

# Admin API key with read/write permissions  
GOVSTACK_ADMIN_API_KEY="your-secure-admin-key-here"

# Strong database password
POSTGRES_PASSWORD="your-strong-db-password"

# Secure database connection string
DATABASE_URL="postgresql+asyncpg://postgres:password@host:5432/db"

# ChromaDB authentication
CHROMA_USERNAME="your-chroma-username"
CHROMA_PASSWORD="your-secure-chroma-password"
CHROMA_CLIENT_AUTHN_CREDENTIALS="username:password"

# MinIO access credentials
MINIO_ACCESS_KEY="your-minio-access-key"  
MINIO_SECRET_KEY="your-minio-secret-key"

• Use cryptographically secure random generators
• Minimum 32 characters length
• Include alphanumeric and special characters
• Avoid predictable patterns

Example secure key format:

GOVSTACK_API_KEY="gs-prod-$(openssl rand -hex 32)"

1. Rotation: Rotate API keys regularly (every 90 days recommended)
2. Storage: Store keys in secure environment variables or secret management systems
3. Scope: Use minimal required permissions for each key
4. Monitoring: Log and monitor API key usage
5. Revocation: Have a process to quickly revoke compromised keys

• Never commit API keys to version control
• Use secure channels for key distribution
• Implement key provisioning workflows
• Document key ownership and purpose

• Use strong, unique API keys
• Configure HTTPS/TLS encryption
• Set secure database passwords
• Enable access logging
• Configure CORS properly
• Disable debug mode (DEV_MODE=false)
• Set appropriate log levels

• Use private networks for database access
• Implement firewall rules
• Regular security updates
• Monitor system resources
• Backup encryption
• Network segmentation

• Rate limiting implementation
• Request size limits
• Input validation
• Output sanitization
• Error message sanitization
• Security headers

• API access logging
• Failed authentication monitoring
• Unusual usage pattern detection
• Security event alerting
• Regular security audits

# Development - Less restrictive but still secure
GOVSTACK_API_KEY="gs-dev-master-key-12345"
GOVSTACK_ADMIN_API_KEY="gs-dev-admin-key-67890"
DEV_MODE=true
LOG_LEVEL=DEBUG

# Production - Maximum security
GOVSTACK_API_KEY="gs-prod-$(openssl rand -hex 32)"
GOVSTACK_ADMIN_API_KEY="gs-prod-admin-$(openssl rand -hex 32)"
DEV_MODE=false
LOG_LEVEL=INFO

# Staging - Production-like security
GOVSTACK_API_KEY="gs-staging-$(openssl rand -hex 24)"
GOVSTACK_ADMIN_API_KEY="gs-staging-admin-$(openssl rand -hex 24)"
DEV_MODE=false
LOG_LEVEL=INFO

The API returns specific error codes for authentication issues:

{
  "detail": "Missing API key",
  "status_code": 401
}

{
  "detail": "Invalid API key", 
  "status_code": 401
}

{
  "detail": "Insufficient permissions for this operation",
  "status_code": 403
}

Recommended security headers for production:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'

1. Immediate: Rotate the compromised key
2. Investigate: Check access logs for unauthorized usage
3. Update: Update all systems using the old key
4. Monitor: Watch for continued unauthorized access attempts
5. Document: Record the incident and response actions

1. Isolate: Restrict access to affected systems
2. Assess: Determine scope and impact
3. Contain: Prevent further unauthorized access
4. Recover: Restore systems from secure backups if needed
5. Learn: Update security measures based on lessons learned

• Encrypt data in transit and at rest
• Implement data retention policies
• Provide data access and deletion capabilities
• Maintain audit trails

• Implement principle of least privilege
• Regular access reviews
• Automated access provisioning/deprovisioning
• Multi-factor authentication for administrative access

• Comprehensive audit logging
• Real-time security monitoring
• Incident response procedures
• Regular security assessments

For security issues:

1. Review this documentation first
2. Check application logs
3. Verify API key configuration
4. Test with appropriate permissions

Remember: Security is a shared responsibility between the API provider and consumers. Follow these guidelines to ensure secure operations.