cp

README.md

@@ -301,6 +301,42 @@ We deliberately decoupled the image embedding process from the upload flow for s
 - **Minimal attack surface**: Limited public endpoints with appropriate rate limiting
 - **Audit logging**: Comprehensive activity tracking for security analysis
 
+### API Key Authentication System
+
+SEREACT uses a simple API key authentication system:
+
+#### Key Generation and Storage
+
+- API keys are generated as cryptographically secure random strings
+- Each team can have multiple API keys
+- Keys are never stored in plaintext - only secure hashes are saved to the database
+
+#### Authentication Flow
+
+1. Client includes the API key in requests via the `X-API-Key` HTTP header
+2. Auth middleware validates the key by:
+   - Hashing the provided key
+   - Querying Firestore for a matching hash
+   - Verifying the key belongs to the appropriate team
+3. Request is either authorized to proceed or rejected with 401/403 status
+
+#### Key Management
+
+- API keys can be created through the API:
+  - User makes an authenticated request
+  - The system generates a new random key and returns it ONCE
+  - Only the hash is stored in the database
+- Keys can be viewed and revoked through dedicated endpoints
+- Each API key use is logged for audit purposes
+
+#### Design Considerations
+
+- No master/global API key exists to eliminate single points of failure
+- All keys are scoped to specific teams to enforce multi-tenant isolation
+- Keys are transmitted only over HTTPS to prevent interception
+
+This authentication approach balances security with usability for machine-to-machine API interactions, while maintaining complete isolation between different teams using the system.
+
 ### Database Structure
 
 The Firestore database is organized into collections and documents with the following structure:
@@ -525,4 +561,4 @@ This modular architecture provides several benefits:
 - **Testability**: Modules can be tested in isolation with mocked dependencies
 - **Scalability**: New features can be added by extending existing modules
 - **Reusability**: Common functionality is centralized for consistent implementation
-- **Security**: Authentication and authorization are handled consistently 
+- **Security**: Authentication and authorization are handled consistently