feat: admin Swagger separation + per-user rate limit multiplier — MAIN

[abs2023]

TL;DR

Two features shipping to production: (1) Admin billing endpoints are now isolated onto a dedicated Swagger page at /admin/docs, removing them from the public API surface; (2) a new per-user rate-limit multiplier lets admins scale RPM/TPM limits up or down for individual users without redeploying.

---

What Changed

1. Dedicated Admin Swagger Page (/admin/docs)

• New file: src/api/v1/billing/admin.py — all admin-protected billing endpoints (staking/settings, staking/refresh, credits/adjust, balance/reconcile, and the new rate-limit multiplier endpoints) have been extracted out of the public billing router into a standalone admin router.
• Public /docs no longer exposes any admin-tagged endpoints. The OpenAPI schema is split at build time: public routes serve from /api/v1/openapi.json, admin routes serve from /admin/api/v1/openapi.json.
• The Swagger HTML builder was refactored into a shared _build_swagger_html() helper to eliminate duplication and strip noisy console.log debug statements from the OAuth2 flow.
• A red "Admin API Docs" link was added to the /api-docs landing page.

2. Per-User Rate Limit Multiplier

• DB migration: add_rate_limit_multiplier_to_users adds a rate_limit_multiplier FLOAT NOT NULL DEFAULT 1.0 column to the users table.
• Model + cache: User.rate_limit_multiplier is now persisted, included in the Redis user cache, and deserialized correctly in all auth dependency paths (get_current_user, get_api_key_auth, _build_auth_from_cache, _build_auth_from_db).
• Rate limit service: check_rate_limit() accepts a multiplier parameter. Limits are scaled at check time — 2.0 doubles RPM/TPM, 0.5 halves them, with a floor of 1 to prevent zero-limit lockout.
• Admin endpoints: POST /billing/rate-limit/multiplier (set) and GET /billing/rate-limit/multiplier/{cognito_user_id} (get), both behind X-Admin-Secret.
• Schemas: RateLimitMultiplierRequest / RateLimitMultiplierResponse added to src/schemas/billing.py.

3. Cleanup

• Removed ~230 lines of admin endpoint code from the public billing/index.py (moved, not deleted).
• Removed unused imports (secrets, Header, staking_service, user_crud, etc.) from the public billing module.

Files Changed (11)

File	Change
alembic/versions/2026_03_10_0001_add_rate_limit_multiplier_to_users.py	New — migration
src/api/v1/__init__.py	Register billing_admin router
src/api/v1/billing/admin.py	New — all admin billing endpoints
src/api/v1/billing/index.py	Remove admin endpoints (moved to admin.py)
src/api/v1/chat/index.py	Minor import
src/api/v1/embeddings/index.py	Minor import
src/db/models/user.py	Add rate_limit_multiplier column
src/dependencies.py	Include rate_limit_multiplier in cache + deserialization
src/main.py	Split OpenAPI schemas, add /admin/docs, refactor Swagger HTML
src/schemas/billing.py	Add rate-limit multiplier request/response models
src/services/rate_limiting/rate_limit_service.py	Apply per-user multiplier to RPM/TPM checks

Risk Assessment

• Low risk — admin endpoints are a code reorganization (same logic, new file), and the rate-limit multiplier defaults to 1.0 (no behavioral change for existing users).
• Migration is additive (ADD COLUMN ... DEFAULT 1.0) — no data loss path.
• Public API contract is unchanged; only admin surface area is affected.

Test Plan

• Verified on TEST environment
• Confirm /docs no longer shows admin-tagged endpoints
• Confirm /admin/docs renders and shows only admin endpoints
• Confirm POST /billing/rate-limit/multiplier sets value and invalidates cache
• Confirm rate limits scale correctly for a user with multiplier ≠ 1.0
• Confirm migration runs cleanly against production schema

Made with Cursor