feat(api): add API Key Management system for programmatic access

- Add
ame and is_active columns to ApiKey model
- Rename last_used to last_used_at for consistency
- Add schema migrations for api_keys table
- Fix create/list/delete endpoints to return proper response models
- Support optional
ame field when creating keys
- Change key prefix from
ag_ to pdf_rag_
- Check is_active in API key authentication middleware

Closes #284

backend/app/auth.py

@@ -77,18 +77,18 @@ def get_current_user(
     token = credentials.credentials
 
     # Check if token is an API key
-    if token.startswith("rag_"):
+    if token.startswith("pdf_rag_"):
         hashed = hashlib.sha256(token.encode("utf-8")).hexdigest()
         from app.models import ApiKey
-        api_key = db.query(ApiKey).filter(ApiKey.hashed_key == hashed).first()
+        api_key = db.query(ApiKey).filter(ApiKey.hashed_key == hashed, ApiKey.is_active == True).first()
         if not api_key:
             raise HTTPException(
                 status_code=status.HTTP_401_UNAUTHORIZED,
                 detail="Invalid API key",
                 headers={"WWW-Authenticate": "Bearer"},
             )
-        
-        api_key.last_used = datetime.now(timezone.utc)
+
+        api_key.last_used_at = datetime.now(timezone.utc)
         db.commit()
 
         user = api_key.user

backend/app/database.py

@@ -71,6 +71,27 @@ def _migrate_schema():
                     "Migration skipped (may already exist): %s.%s", table, column
                 )
 
+    # Migrate api_keys
+    try:
+        existing_keys_columns = {c["name"] for c in inspector.get_columns("api_keys")}
+    except Exception:
+        existing_keys_columns = set()
+    keys_migrations = [
+        ("api_keys", "name", "ALTER TABLE api_keys ADD COLUMN name VARCHAR(100) DEFAULT 'default'"),
+        ("api_keys", "is_active", "ALTER TABLE api_keys ADD COLUMN is_active BOOLEAN DEFAULT 1 NOT NULL"),
+        ("api_keys", "last_used_at", "ALTER TABLE api_keys ADD COLUMN last_used_at TIMESTAMP"),
+    ]
+    for table, column, ddl in keys_migrations:
+        if column not in existing_keys_columns:
+            try:
+                with engine.begin() as conn:
+                    conn.execute(text(ddl))
+                logger.info("Migration: added column %s.%s", table, column)
+            except Exception:
+                logger.warning(
+                    "Migration skipped (may already exist): %s.%s", table, column
+                )
+
     # Migrate documents
     existing_docs_columns = {c["name"] for c in inspector.get_columns("documents")}
     docs_migrations = [

backend/app/models.py

@@ -134,10 +134,12 @@ class ApiKey(Base):
 
     id = Column(GUID, primary_key=True, default=uuid.uuid4)
     user_id = Column(GUID, ForeignKey("users.id"), nullable=False, index=True)
-    key_prefix = Column(String(10), nullable=False)
+    name = Column(String(100), nullable=False, default="default")
+    key_prefix = Column(String(20), nullable=False)
     hashed_key = Column(String(255), nullable=False, unique=True, index=True)
+    is_active = Column(Boolean, default=True, nullable=False)
     created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))
-    last_used = Column(DateTime, nullable=True)
+    last_used_at = Column(DateTime, nullable=True)
 
     # Relationships
     user = relationship("User", back_populates="api_keys")

backend/app/routes/auth.py

@@ -4,7 +4,7 @@ Auth API routes — register, login, and user profile.
 import re
 import secrets
 from datetime import datetime, timezone
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Body, Depends, HTTPException, status
 from langsmith import expect
 from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.orm import Session
@@ -419,26 +419,48 @@ from typing import List
 import hashlib
 
 @router.post("/api-keys", response_model=ApiKeyCreateResponse, status_code=status.HTTP_201_CREATED)
-def create_api_key(user: User = Depends(get_current_user), db: Session = Depends(get_db)):
+def create_api_key(
+    user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    body: dict = Body(None),
+):
     """Create a new API key for the authenticated user."""
-    raw_key = "rag_" + secrets.token_urlsafe(32)
+    name = (body or {}).get("name", "default")
+    raw_key = "pdf_rag_" + secrets.token_hex(24)
     hashed_key = hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
-    
+
     api_key = ApiKey(
         user_id=user.id,
-        key_prefix=raw_key[:10],
+        name=name,
+        key_prefix=raw_key[:15],
         hashed_key=hashed_key,
+        is_active=True,
     )
     db.add(api_key)
     db.commit()
     db.refresh(api_key)
-    
-    return {"key": raw_key, "api_key": api_key}
+
+    return ApiKeyCreateResponse(
+        id=str(api_key.id),
+        name=api_key.name,
+        key_preview=api_key.key_prefix,
+        created_at=api_key.created_at,
+        raw_key=raw_key,
+    )
 
 @router.get("/api-keys", response_model=List[ApiKeyResponse])
 def list_api_keys(user: User = Depends(get_current_user), db: Session = Depends(get_db)):
     """List all API keys for the authenticated user."""
-    return db.query(ApiKey).filter(ApiKey.user_id == user.id).all()
+    keys = db.query(ApiKey).filter(ApiKey.user_id == user.id, ApiKey.is_active == True).all()
+    return [
+        ApiKeyResponse(
+            id=str(k.id),
+            name=k.name,
+            key_preview=k.key_prefix,
+            created_at=k.created_at,
+        )
+        for k in keys
+    ]
 
 @router.delete("/api-keys/{key_id}", status_code=status.HTTP_204_NO_CONTENT)
 def delete_api_key(key_id: str, user: User = Depends(get_current_user), db: Session = Depends(get_db)):
@@ -446,7 +468,7 @@ def delete_api_key(key_id: str, user: User = Depends(get_current_user), db: Sess
     api_key = db.query(ApiKey).filter(ApiKey.id == key_id, ApiKey.user_id == user.id).first()
     if not api_key:
         raise HTTPException(status_code=404, detail="API key not found")
-    
+
     db.delete(api_key)
     db.commit()
     return None

backend/app/schemas.py

@@ -61,6 +61,7 @@ class HFTokenUpdate(BaseModel):
 
 class ApiKeyResponse(BaseModel):
     id: str
+    name: str
     key_preview: str
     created_at: datetime
 
@@ -68,9 +69,16 @@ class ApiKeyResponse(BaseModel):
         from_attributes = True
 
 
-class ApiKeyCreateResponse(ApiKeyResponse):
+class ApiKeyCreateResponse(BaseModel):
+    id: str
+    name: str
+    key_preview: str
+    created_at: datetime
     raw_key: str
 
+    class Config:
+        from_attributes = True
+
 
 class UserResponse(BaseModel):
     id: str