feat: track API key last usage timestamp

Add `last_used_at` field to track when API keys are used for security
auditing. This enables identification of stale/unused API keys.

- Add `last_used_at` nullable datetime field to ApiKey model
- Update timestamp in `ApiKeyAuth.__call__()` on successful auth
- Expose field in `ApiKeyResponse` schema
- Add migration for the new column
- Add test to verify timestamp is updated

Closes SECURITY-REVIEW.md `#23`

Author: seapagan

SECURITY-REVIEW.md

@@ -407,14 +407,18 @@
 
 ### 23. API Key last_used_at Never Updated
 
-**Location**: `app/models/api_key.py:26` (field defined),
-`app/managers/api_key.py:155-248` (never updated)
-
-- **Issue**: The `last_used_at` field exists in the model but is **never
-  maintained**, making it impossible to identify stale/unused API keys for
-  security audits.
-- **Fix**: Update `last_used_at` in `ApiKeyAuth.__call__()` after successful
-  validation.
+> [!NOTE]
+> ✅ **Done**: Added `last_used_at` field to ApiKey model and update it in
+> `ApiKeyAuth.__call__()` after successful validation. Field is exposed in
+> `ApiKeyResponse` schema for security auditing.
+
+**Location**: `app/models/api_key.py:27` (field defined),
+`app/managers/api_key.py:155-254` (updated on successful auth)
+
+- **Issue**: The `last_used_at` field did not exist in the model, making it
+  impossible to identify stale/unused API keys for security audits.
+- **Fix**: Added `last_used_at` field and update it in `ApiKeyAuth.__call__()`
+  after successful validation.
 
 ### 24. No Password Required for Self-Service Password Change
 

app/managers/api_key.py

@@ -3,6 +3,7 @@
 import hashlib
 import hmac
 import secrets
+from datetime import datetime, timezone
 from uuid import UUID
 
 from fastapi import Depends, HTTPException, Request, status
@@ -238,6 +239,9 @@ async def __call__(  # noqa: C901, PLR0911, PLR0912
         request.state.user = user
         request.state.api_key = key
 
+        # Update last_used_at timestamp
+        key.last_used_at = datetime.now(timezone.utc)
+
         increment_api_key_validation("valid")
         category_logger.info(
             f"API key authenticated: '{key.name}' (ID: {key.id}) for user "

app/migrations/versions/2026_01_23_2115-add_last_used_at_to_api_keys.py

@@ -0,0 +1,31 @@
+"""Add last_used_at column to api_keys table.
+
+Revision ID: add_last_used_at
+Revises: add_api_keys_table
+Create Date: 2026-01-23 21:15:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "add_last_used_at"
+down_revision: Union[str, None] = "add_api_keys_table"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add last_used_at column to api_keys table."""
+    op.add_column(
+        "api_keys",
+        sa.Column("last_used_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    """Remove last_used_at column from api_keys table."""
+    op.drop_column("api_keys", "last_used_at")

app/models/api_key.py

@@ -25,6 +25,9 @@ class ApiKey(Base):
         DateTime(timezone=True), default=datetime.now(timezone.utc)
     )
     is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    last_used_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True, default=None
+    )
     scopes: Mapped[list[str]] = mapped_column(ARRAY(String), nullable=True)
 
     # Relationship to User

app/schemas/response/api_key.py

@@ -15,6 +15,7 @@ class ApiKeyResponse(BaseModel):
     name: str
     created_at: datetime
     is_active: bool
+    last_used_at: datetime | None = None
     scopes: list[str] | None = None
 
 

tests/unit/test_api_key_auth.py

@@ -248,3 +248,35 @@ async def test_api_key_auth_unverified_user_no_auto_error(
         result = await auth(request=mock_req, db=test_db)
 
         assert result is None
+
+    async def test_api_key_auth_updates_last_used_at(
+        self, test_db, mocker
+    ) -> None:
+        """Test that last_used_at is updated on successful authentication."""
+        # Create a user and API key
+        _ = await UserManager.register(self.test_user, test_db)
+        user = await UserManager.get_user_by_email(
+            self.test_user["email"], test_db
+        )
+        api_key, raw_key = await ApiKeyManager.create_key(
+            user, "Test Key", None, test_db
+        )
+
+        # Verify last_used_at is None initially
+        assert api_key.last_used_at is None
+
+        # Authenticate with the API key
+        mock_req = mocker.patch(self.mock_request_path)
+        mock_req.headers = {"X-API-Key": raw_key}
+
+        auth = ApiKeyAuth()
+        await auth(request=mock_req, db=test_db)
+
+        # Flush to ensure changes are persisted
+        await test_db.flush()
+
+        # Refresh the api_key object from the database
+        await test_db.refresh(api_key)
+
+        # Verify last_used_at is now set
+        assert api_key.last_used_at is not None