feat: API key list + revoke endpoints, specific 401 errors (OPE-164)

Backend:
- GET /api/v1/keys -- list user's API keys (masked, with metadata)
- DELETE /api/v1/keys/{key_id} -- revoke by ID (soft delete, verifies ownership)
- APIKeyManager.list_keys(user_id) -- returns masked keys with preview
- APIKeyManager.revoke_key_by_id(key_id, user_id) -- ownership-safe revoke

Auth:
- Specific 401 errors for ci_ keys: 'not found', 'revoked', 'no linked user'
  instead of generic 'Invalid token or API key'
- Would have saved us 2 hours of debugging today

Existing endpoints (unchanged):
- POST /api/v1/keys/generate -- already existed, works
- GET /api/v1/keys/usage -- already existed, works

392 tests pass.

Author: DevanshuNEU

backend/middleware/auth.py

@@ -160,10 +160,31 @@ def _authenticate(token: str) -> AuthContext:
         set_user_context(user_id=ctx.user_id or ctx.api_key_name)
         return ctx
 
-    # Neither worked
+    # Provide specific error for ci_ keys so users can debug
+    if token.startswith("ci_"):
+        try:
+            from services.supabase_service import get_supabase_service
+            db = get_supabase_service().client
+            key_hash = hashlib.sha256(token.encode()).hexdigest()
+            result = db.table("api_keys").select(
+                "active, user_id"
+            ).eq("key_hash", key_hash).execute()
+            if not result.data:
+                detail = "API key not found. Check that the key is correct."
+            elif not result.data[0].get("active"):
+                detail = "API key has been revoked."
+            elif not result.data[0].get("user_id"):
+                detail = "API key has no linked user. Contact admin."
+            else:
+                detail = "API key validation failed."
+        except Exception:
+            detail = "API key validation failed."
+    else:
+        detail = "Invalid token or API key"
+
     raise HTTPException(
         status_code=status.HTTP_401_UNAUTHORIZED,
-        detail="Invalid token or API key",
+        detail=detail,
         headers={"WWW-Authenticate": "Bearer"}
     )
 

backend/routes/api_keys.py

@@ -93,6 +93,49 @@ async def generate_api_key(
         raise HTTPException(status_code=500, detail="Failed to generate API key")
 
 
+@router.get("/keys")
+async def list_api_keys(
+    auth: AuthContext = Depends(require_auth)
+):
+    """List all API keys for the authenticated user."""
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    try:
+        keys = api_key_manager.list_keys(auth.user_id)
+        return {"keys": keys}
+    except Exception as e:
+        logger.error("Failed to list API keys", user_id=auth.user_id, error=str(e))
+        capture_exception(e, operation="list_api_keys", user_id=auth.user_id)
+        raise HTTPException(status_code=500, detail="Failed to list API keys")
+
+
+@router.delete("/keys/{key_id}")
+async def revoke_api_key(
+    key_id: str,
+    auth: AuthContext = Depends(require_auth)
+):
+    """Revoke an API key by ID. Soft-deletes (sets active=false)."""
+    if not auth.user_id:
+        raise HTTPException(status_code=401, detail="User ID required")
+
+    try:
+        success = api_key_manager.revoke_key_by_id(key_id, auth.user_id)
+        if not success:
+            raise HTTPException(
+                status_code=404,
+                detail="API key not found or not owned by you"
+            )
+        logger.info("API key revoked", user_id=auth.user_id, key_id=key_id)
+        return {"message": "API key revoked", "key_id": key_id}
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to revoke API key", user_id=auth.user_id, error=str(e))
+        capture_exception(e, operation="revoke_api_key", user_id=auth.user_id)
+        raise HTTPException(status_code=500, detail="Failed to revoke API key")
+
+
 @router.get("/keys/usage")
 async def get_api_usage(
     auth: AuthContext = Depends(require_auth)

backend/services/rate_limiter.py

@@ -204,7 +204,33 @@ def verify_key(self, api_key: str) -> Optional[Dict]:
         return result.data[0] if result.data else None
 
     def revoke_key(self, api_key: str) -> bool:
-        """Revoke an API key"""
+        """Revoke an API key by raw key value"""
         key_hash = hashlib.sha256(api_key.encode()).hexdigest()
         self.db.table("api_keys").update({"active": False}).eq("key_hash", key_hash).execute()
         return True
+
+    def revoke_key_by_id(self, key_id: str, user_id: str) -> bool:
+        """Revoke an API key by UUID. Verifies ownership via user_id."""
+        result = self.db.table("api_keys").update(
+            {"active": False}
+        ).eq("id", key_id).eq("user_id", user_id).execute()
+        return len(result.data) > 0
+
+    def list_keys(self, user_id: str) -> list:
+        """List all API keys for a user. Returns masked keys (no raw values)."""
+        result = self.db.table("api_keys").select(
+            "id, name, tier, active, created_at, last_used_at, key_hash"
+        ).eq("user_id", user_id).order("created_at", desc=True).execute()
+        keys = []
+        for row in result.data:
+            h = row.get("key_hash", "")
+            keys.append({
+                "id": row["id"],
+                "name": row["name"],
+                "tier": row["tier"],
+                "active": row["active"],
+                "created_at": row["created_at"],
+                "last_used_at": row.get("last_used_at"),
+                "key_preview": f"ci_...{h[-8:]}" if h else "ci_...",
+            })
+        return keys