From af38411d0c8aed5dea627cca98119423ffac1741 Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 14:29:35 +0200
Subject: [PATCH 1/8] feat(api+frontend/admin): per-API-key usage stats (closes
 #340/#344 scope)

Revives the deferred "API keys usage stats" sub-task from #340/#344
(prior PR #380 closed stale). Fresh implementation against current
main using #380's body as spec.

Backend: migration 000094 adds request_count_total/request_count_24h
counters to api_keys, plus an atomic RecordAPIKeyUsage store method
that increments both alongside last_used_at with a rolling 24h window.
New GET /api/api-keys/usage-stats aggregates the calling user's own
keys into a section summary (active count, 24h/lifetime totals, top-3
most active). OpenAPI updated.

Frontend: Admin -> API Keys now shows a 3-tile summary card (active
keys, requests 24h, requests lifetime) + a top-3 most-active list,
plus per-row Requests (24h) / Requests (total) columns. Loading
skeletons via lib/skeleton; summary errors stay isolated from list
errors.

Migration numbered 000094 (not #380's stale 000051) since 000093 is
already claimed by in-flight PR #1516.
---
 frontend/src/__tests__/api-apikeys.test.ts    |  41 +++++
 frontend/src/__tests__/apikeys.test.ts        | 139 +++++++++++++++
 frontend/src/api/apikeys.ts                   |  16 +-
 frontend/src/api/index.ts                     |   3 +
 frontend/src/api/types.ts                     |  20 +++
 frontend/src/apikeys.ts                       | 164 ++++++++++++++++++
 frontend/src/index.html                       |   3 +
 frontend/src/styles/components.css            |  67 +++++++
 frontend/src/types.ts                         |   6 +
 internal/api/handler_apikeys.go               |  21 +++
 internal/api/handler_apikeys_test.go          |  87 ++++++++++
 internal/api/handler_ri_exchange_test.go      |   3 +
 internal/api/mocks_test.go                    |   5 +
 internal/api/openapi.yaml                     |  64 +++++++
 internal/api/router.go                        |   9 +-
 internal/api/types.go                         |   4 +
 internal/auth/interfaces.go                   |   5 +
 internal/auth/service_apikeys.go              |  29 +++-
 internal/auth/service_apikeys_api.go          | 128 ++++++++++++--
 internal/auth/service_apikeys_api_test.go     | 127 +++++++++++++-
 internal/auth/service_apikeys_test.go         |  46 ++++-
 internal/auth/service_security_test.go        |   8 +-
 internal/auth/store_postgres.go               |  57 +++++-
 internal/auth/store_postgres_pgxmock_test.go  |  47 +++++
 internal/auth/test_helpers.go                 |   5 +
 internal/auth/types.go                        |   6 +
 .../000094_api_keys_usage_counters.down.sql   |   5 +
 .../000094_api_keys_usage_counters.up.sql     |  25 +++
 internal/mocks/stores.go                      |   6 +
 internal/server/app.go                        |   4 +
 internal/server/health_test.go                |   4 +
 31 files changed, 1113 insertions(+), 41 deletions(-)
 create mode 100644 internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
 create mode 100644 internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql

diff --git a/frontend/src/__tests__/api-apikeys.test.ts b/frontend/src/__tests__/api-apikeys.test.ts
index e54471c1d..960d2752d 100644
--- a/frontend/src/__tests__/api-apikeys.test.ts
+++ b/frontend/src/__tests__/api-apikeys.test.ts
@@ -5,6 +5,7 @@
 import { fetchMock } from './setup';
 import {
   getApiKeys,
+  getApiKeysUsageStats,
   createApiKey,
   revokeApiKey,
   deleteApiKey
@@ -56,6 +57,46 @@ describe('API Keys API Module', () => {
     });
   });
 
+  describe('getApiKeysUsageStats', () => {
+    test('fetches section-level usage summary', async () => {
+      const mockResponse = {
+        total_active: 2,
+        total_requests_24h: 42,
+        total_requests_lifetime: 1234,
+        top_keys: [
+          { id: 'key-1', name: 'Busy', key_prefix: 'abc12345', request_count_24h: 30 },
+        ],
+      };
+
+      fetchMock.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+      const result = await getApiKeysUsageStats();
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        '/api/api-keys/usage-stats',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            'X-Authorization': 'Bearer test-token',
+          }),
+        })
+      );
+      expect(result).toEqual(mockResponse);
+    });
+
+    test('throws error on API failure', async () => {
+      fetchMock.mockResolvedValue({
+        ok: false,
+        status: 401,
+        json: () => Promise.resolve({ error: 'Unauthorized' }),
+      });
+
+      await expect(getApiKeysUsageStats()).rejects.toThrow('Unauthorized');
+    });
+  });
+
   describe('createApiKey', () => {
     test('creates API key with name only', async () => {
       const mockResponse = {
diff --git a/frontend/src/__tests__/apikeys.test.ts b/frontend/src/__tests__/apikeys.test.ts
index 3cc12f54b..ec3b94401 100644
--- a/frontend/src/__tests__/apikeys.test.ts
+++ b/frontend/src/__tests__/apikeys.test.ts
@@ -17,6 +17,7 @@ import {
 // Mock the api module
 jest.mock('../api', () => ({
   getApiKeys: jest.fn(),
+  getApiKeysUsageStats: jest.fn(),
   createApiKey: jest.fn(),
   revokeApiKey: jest.fn(),
   deleteApiKey: jest.fn()
@@ -36,6 +37,7 @@ describe('API Keys Module', () => {
   beforeEach(() => {
     // Reset DOM
     document.body.innerHTML = `
+      <div id="apikeys-usage-summary"></div>
       <div id="apikeys-list"></div>
       <button id="create-apikey-btn"></button>
       <div id="create-apikey-modal" class="hidden">
@@ -59,6 +61,15 @@ describe('API Keys Module', () => {
     // clears call history, not the mockResolvedValueOnce queue.
     mockConfirmDialog.mockReset();
     mockConfirmDialog.mockImplementation(() => Promise.resolve(true));
+    // Default the usage-stats endpoint to an empty response so the
+    // parallel-load path in loadApiKeys doesn't reject in tests that
+    // only set up `getApiKeys`. Individual tests can override.
+    (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
+      total_active: 0,
+      total_requests_24h: 0,
+      total_requests_lifetime: 0,
+      top_keys: [],
+    });
   });
 
   describe('loadApiKeys', () => {
@@ -1000,4 +1011,132 @@ describe('API Keys Module', () => {
       expect(span?.getAttribute('title')).toBe(new Date(recentTs).toISOString());
     });
   });
+
+  // Usage stats (issue #340/#344 deferred sub-task) — section-level summary
+  // card above the table + per-row request count columns.
+  describe('Usage stats', () => {
+    test('renders summary tiles when stats load successfully', async () => {
+      (api.getApiKeys as jest.Mock).mockResolvedValue({ api_keys: [] });
+      (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
+        total_active: 2,
+        total_requests_24h: 42,
+        total_requests_lifetime: 1234,
+        top_keys: [
+          { id: 'key-1', name: 'Busy', key_prefix: 'aaaa1111', request_count_24h: 30 },
+          { id: 'key-2', name: 'Medium', key_prefix: 'bbbb2222', request_count_24h: 12 },
+        ],
+      });
+
+      await loadApiKeys();
+      // Allow the parallel stats fetch to resolve.
+      await new Promise((r) => setTimeout(r, 0));
+
+      const summary = document.getElementById('apikeys-usage-summary');
+      expect(summary?.textContent).toContain('Active keys');
+      expect(summary?.textContent).toContain('2');
+      expect(summary?.textContent).toContain('Requests (24h)');
+      expect(summary?.textContent).toContain('42');
+      expect(summary?.textContent).toContain('Requests (lifetime)');
+      // formatCount abbreviates large numbers in the summary tiles to
+      // fit the tile width — table cells keep the exact integer.
+      expect(summary?.textContent).toContain('1.2k');
+      expect(summary?.textContent).toContain('Most active (24h)');
+      expect(summary?.textContent).toContain('Busy');
+      expect(summary?.textContent).toContain('aaaa1111');
+    });
+
+    test('omits top-list when no key has 24h activity', async () => {
+      (api.getApiKeys as jest.Mock).mockResolvedValue({ api_keys: [] });
+      (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
+        total_active: 1,
+        total_requests_24h: 0,
+        total_requests_lifetime: 7,
+        top_keys: [],
+      });
+
+      await loadApiKeys();
+      await new Promise((r) => setTimeout(r, 0));
+
+      const summary = document.getElementById('apikeys-usage-summary');
+      expect(summary?.textContent).not.toContain('Most active (24h)');
+    });
+
+    test('shows inline error when stats endpoint fails, table still renders', async () => {
+      (api.getApiKeys as jest.Mock).mockResolvedValue({
+        api_keys: [
+          { id: 'key-1', name: 'k', key_prefix: 'abc12345', is_active: true, created_at: '2024-01-15T10:00:00Z' },
+        ],
+      });
+      (api.getApiKeysUsageStats as jest.Mock).mockRejectedValue(new Error('boom'));
+
+      await loadApiKeys();
+      await new Promise((r) => setTimeout(r, 0));
+
+      const summary = document.getElementById('apikeys-usage-summary');
+      expect(summary?.querySelector('.error')?.textContent).toBe('Failed to load usage summary');
+      // The table itself still renders despite the summary failure.
+      const list = document.getElementById('apikeys-list');
+      expect(list?.innerHTML).toContain('abc12345');
+    });
+
+    test('renders Requests (24h) and Requests (total) columns per row', async () => {
+      (api.getApiKeys as jest.Mock).mockResolvedValue({
+        api_keys: [
+          {
+            id: 'key-1',
+            name: 'k1',
+            key_prefix: 'abc12345',
+            is_active: true,
+            created_at: '2024-01-15T10:00:00Z',
+            request_count_24h: 12,
+            request_count_total: 1234,
+          },
+        ],
+      });
+
+      await loadApiKeys();
+
+      const container = document.getElementById('apikeys-list');
+      expect(container?.innerHTML).toContain('Requests (24h)');
+      expect(container?.innerHTML).toContain('Requests (total)');
+      // Counts render with thousands separator for readability.
+      expect(container?.innerHTML).toContain('1,234');
+      expect(container?.innerHTML).toContain('apikeys-count-cell');
+    });
+
+    test('falls back to 0 when counter fields are missing from the response', async () => {
+      (api.getApiKeys as jest.Mock).mockResolvedValue({
+        api_keys: [
+          // No request_count_* fields — simulates a cached older response.
+          { id: 'key-1', name: 'k1', key_prefix: 'abc12345', is_active: true, created_at: '2024-01-15T10:00:00Z' },
+        ],
+      });
+
+      await loadApiKeys();
+
+      const container = document.getElementById('apikeys-list');
+      const cells = container?.querySelectorAll('.apikeys-count-cell');
+      expect(cells?.length).toBe(2);
+      expect(cells?.[0]?.textContent).toBe('0');
+      expect(cells?.[1]?.textContent).toBe('0');
+    });
+
+    test('list-fetch failure clears summary skeleton and shows error', async () => {
+      (api.getApiKeys as jest.Mock).mockRejectedValue(new Error('list boom'));
+      (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
+        total_active: 0,
+        total_requests_24h: 0,
+        total_requests_lifetime: 0,
+        top_keys: [],
+      });
+
+      await loadApiKeys();
+      await new Promise((r) => setTimeout(r, 0));
+
+      const list = document.getElementById('apikeys-list');
+      expect(list?.querySelector('.error')?.textContent).toBe('Failed to load API keys');
+      // The skeleton-active marker is gone (success/error both clear it).
+      expect(list?.dataset['skeletonActive']).toBeUndefined();
+    });
+  });
 });
diff --git a/frontend/src/api/apikeys.ts b/frontend/src/api/apikeys.ts
index 6659b8790..b70901ae0 100644
--- a/frontend/src/api/apikeys.ts
+++ b/frontend/src/api/apikeys.ts
@@ -3,7 +3,12 @@
  */
 
 import { apiRequest } from './client';
-import type { GetAPIKeysResponse, CreateAPIKeyRequest, CreateAPIKeyResponse } from './types';
+import type {
+  GetAPIKeysResponse,
+  CreateAPIKeyRequest,
+  CreateAPIKeyResponse,
+  APIKeysUsageStats,
+} from './types';
 
 /**
  * Get all API keys
@@ -12,6 +17,15 @@ export async function getApiKeys(): Promise<GetAPIKeysResponse> {
   return apiRequest<GetAPIKeysResponse>('/api-keys');
 }
 
+/**
+ * Get section-level API keys usage stats (issue #340/#344 deferred
+ * sub-task). Returns the per-section summary card -- totals + top keys
+ * by 24h activity. Scoped to the calling user's own keys.
+ */
+export async function getApiKeysUsageStats(): Promise<APIKeysUsageStats> {
+  return apiRequest<APIKeysUsageStats>('/api-keys/usage-stats');
+}
+
 /**
  * Create a new API key
  */
diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts
index 8b5c3e22f..dd7f8ffff 100644
--- a/frontend/src/api/index.ts
+++ b/frontend/src/api/index.ts
@@ -40,6 +40,8 @@ export type {
   CreateAPIKeyRequest,
   CreateAPIKeyResponse,
   GetAPIKeysResponse,
+  APIKeysUsageStats,
+  APIKeysUsageStatsTopKey,
   SavingsAnalyticsResponse,
   SavingsAnalyticsSummary,
   SavingsDataPoint,
@@ -169,6 +171,7 @@ export {
 // Re-export apikeys functions
 export {
   getApiKeys,
+  getApiKeysUsageStats,
   createApiKey,
   revokeApiKey,
   deleteApiKey
diff --git a/frontend/src/api/types.ts b/frontend/src/api/types.ts
index 754393b78..4ce65be5f 100644
--- a/frontend/src/api/types.ts
+++ b/frontend/src/api/types.ts
@@ -575,6 +575,26 @@ export interface APIKeyInfo {
   created_at: string;
   last_used_at?: string;
   permissions?: Permission[];
+  // Usage counters (issue #340/#344 deferred sub-task).
+  // Optional in the type so older mock data / cached responses without
+  // the columns don't blow up the renderer -- but the backend always
+  // sends them as of migration 000094.
+  request_count_total?: number;
+  request_count_24h?: number;
+}
+
+export interface APIKeysUsageStatsTopKey {
+  id: string;
+  name: string;
+  key_prefix: string;
+  request_count_24h: number;
+}
+
+export interface APIKeysUsageStats {
+  total_active: number;
+  total_requests_24h: number;
+  total_requests_lifetime: number;
+  top_keys: APIKeysUsageStatsTopKey[];
 }
 
 export interface CreateAPIKeyRequest {
diff --git a/frontend/src/apikeys.ts b/frontend/src/apikeys.ts
index ee358e9b7..f40e38255 100644
--- a/frontend/src/apikeys.ts
+++ b/frontend/src/apikeys.ts
@@ -4,10 +4,12 @@
 
 import * as api from './api';
 import type { APIKeyInfo, CreateAPIKeyResponse } from './types';
+import type { APIKeysUsageStats } from './api/types';
 import { escapeHtml, formatDateTime, formatRelativeTime } from './utils';
 import { confirmDialog } from './confirmDialog';
 import { showToast } from './toast';
 import { openModal, closeModal } from './modal';
+import { showSkeletonRows, showSkeletonBlock, teardownSkeleton } from './lib/skeleton';
 
 // State for modal management
 let currentApiKeys: APIKeyInfo[] = [];
@@ -22,8 +24,20 @@ let currentApiKeys: APIKeyInfo[] = [];
  * Read the documented `api_keys` field, then fall back to a bare array
  * (some other deployments/proxies might unwrap) and finally to `[]` so
  * a contract drift can never crash the page.
+ *
+ * The usage-stats summary loads in parallel -- a failure in either path
+ * only takes down its own region, never both. See loadApiKeysUsageStats
+ * for the section header's lifecycle.
  */
 export async function loadApiKeys(): Promise<void> {
+  const listContainer = document.getElementById('apikeys-list');
+  if (listContainer) {
+    showSkeletonRows(listContainer, 3, 9);
+  }
+  // Kick the summary off in parallel -- it has its own container + error
+  // path so we don't await it inside the list flow.
+  void loadApiKeysUsageStats();
+
   try {
     const response = await api.getApiKeys();
     const list = (response as { api_keys?: APIKeyInfo[] } | undefined)?.api_keys
@@ -33,10 +47,133 @@ export async function loadApiKeys(): Promise<void> {
     renderApiKeysList();
   } catch (error) {
     console.error('Failed to load API keys:', error);
+    if (listContainer) teardownSkeleton(listContainer);
+    renderApiKeysListError(listContainer, 'Failed to load API keys');
     showError('Failed to load API keys');
   }
 }
 
+/**
+ * Replace the API keys list region with an inline error message so the
+ * shimmer skeleton doesn't sit beside a stale empty table after a
+ * failed fetch. Uses textContent (no innerHTML) to stay XSS-safe and
+ * matches the patterns used by other modules (e.g. dashboard.ts).
+ */
+function renderApiKeysListError(container: HTMLElement | null, message: string): void {
+  if (!container) return;
+  container.replaceChildren();
+  const p = document.createElement('p');
+  p.className = 'error';
+  p.textContent = message;
+  container.appendChild(p);
+}
+
+/**
+ * Load and render the section-level usage summary (totals + top keys).
+ * Fails closed: on error the summary slot shows an inline message and
+ * the rest of the section still works.
+ */
+export async function loadApiKeysUsageStats(): Promise<void> {
+  const container = document.getElementById('apikeys-usage-summary');
+  if (!container) return;
+  showSkeletonBlock(container, '100%', '4rem');
+  try {
+    const stats = await api.getApiKeysUsageStats();
+    renderApiKeysUsageSummary(stats);
+  } catch (error) {
+    console.error('Failed to load API keys usage stats:', error);
+    teardownSkeleton(container);
+    const p = document.createElement('p');
+    p.className = 'error';
+    p.textContent = 'Failed to load usage summary';
+    container.appendChild(p);
+  }
+}
+
+/**
+ * Render the section-level summary card: total active keys, total
+ * requests (24h + lifetime), and a top-3 most-active row. Built with
+ * createElement only (no innerHTML) to match the codebase XSS posture.
+ */
+export function renderApiKeysUsageSummary(stats: APIKeysUsageStats): void {
+  const container = document.getElementById('apikeys-usage-summary');
+  if (!container) return;
+  container.replaceChildren();
+  delete container.dataset['skeletonActive'];
+
+  const card = document.createElement('div');
+  card.className = 'apikeys-usage-summary card';
+
+  const tiles = document.createElement('div');
+  tiles.className = 'apikeys-usage-tiles';
+  tiles.appendChild(buildSummaryTile('Active keys', String(stats.total_active)));
+  tiles.appendChild(buildSummaryTile('Requests (24h)', formatCount(stats.total_requests_24h)));
+  tiles.appendChild(buildSummaryTile('Requests (lifetime)', formatCount(stats.total_requests_lifetime)));
+  card.appendChild(tiles);
+
+  if (stats.top_keys && stats.top_keys.length > 0) {
+    const heading = document.createElement('h5');
+    heading.className = 'apikeys-usage-top-heading';
+    heading.textContent = 'Most active (24h)';
+    card.appendChild(heading);
+
+    const list = document.createElement('ul');
+    list.className = 'apikeys-usage-top-list';
+    for (const top of stats.top_keys) {
+      const li = document.createElement('li');
+      const name = document.createElement('strong');
+      name.textContent = top.name;
+      const code = document.createElement('code');
+      code.textContent = `${top.key_prefix}...`;
+      const count = document.createElement('span');
+      count.className = 'apikeys-usage-top-count';
+      count.textContent = `${formatCount(top.request_count_24h)} req`;
+      li.appendChild(name);
+      li.appendChild(document.createTextNode(' '));
+      li.appendChild(code);
+      li.appendChild(document.createTextNode(' — '));
+      li.appendChild(count);
+      list.appendChild(li);
+    }
+    card.appendChild(list);
+  }
+
+  container.appendChild(card);
+}
+
+function buildSummaryTile(label: string, value: string): HTMLElement {
+  const tile = document.createElement('div');
+  tile.className = 'apikeys-usage-tile';
+  const labelEl = document.createElement('div');
+  labelEl.className = 'apikeys-usage-tile-label';
+  labelEl.textContent = label;
+  const valueEl = document.createElement('div');
+  valueEl.className = 'apikeys-usage-tile-value';
+  valueEl.textContent = value;
+  tile.appendChild(labelEl);
+  tile.appendChild(valueEl);
+  return tile;
+}
+
+/**
+ * Format a request count for display in the summary tiles. Uses the
+ * standard "k" / "M" abbreviation for large values so the tile doesn't
+ * have to fit "1,234,567" -- the per-row table cells still show the
+ * exact number via formatRequestCount.
+ */
+function formatCount(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return '0';
+  if (n < 1000) return String(Math.trunc(n));
+  if (n < 1_000_000) {
+    // Round to the chosen precision FIRST so we can detect the
+    // 999,500..999,999 band that rounds up to 1000k and promote
+    // it to the M branch instead of emitting "1000k".
+    const k = Number((n / 1000).toFixed(n < 10_000 ? 1 : 0));
+    if (k < 1000) return `${k}k`;
+  }
+  return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 1 : 0)}M`;
+}
+
 /**
  * Render API keys list
  */
@@ -48,6 +185,7 @@ export function renderApiKeysList(): void {
     // DOM construction rather than template literal so the security hook
     // doesn't flag the innerHTML write — and all copy is static anyway.
     container.replaceChildren();
+    delete container.dataset['skeletonActive'];
     const wrap = document.createElement('div');
     wrap.className = 'empty apikeys-empty';
     const h = document.createElement('h4');
@@ -69,6 +207,8 @@ export function renderApiKeysList(): void {
           <th>Status</th>
           <th>Created</th>
           <th>Last Used</th>
+          <th>Requests (24h)</th>
+          <th>Requests (total)</th>
           <th>Expires</th>
           <th>Actions</th>
         </tr>
@@ -78,6 +218,8 @@ export function renderApiKeysList(): void {
           const isExpired = key.expires_at && new Date(key.expires_at) < new Date();
           const statusClass = !key.is_active ? 'badge-danger' : isExpired ? 'badge-warning' : 'badge-success';
           const statusText = !key.is_active ? 'Revoked' : isExpired ? 'Expired' : 'Active';
+          const count24h = formatRequestCount(key.request_count_24h);
+          const countTotal = formatRequestCount(key.request_count_total);
 
           return `
             <tr>
@@ -86,6 +228,8 @@ export function renderApiKeysList(): void {
               <td><span class="badge ${statusClass}">${statusText}</span></td>
               <td>${formatDateTime(key.created_at)}</td>
               <td>${key.last_used_at ? `<span title="${escapeHtml(new Date(key.last_used_at).toISOString())}">${escapeHtml(formatRelativeTime(key.last_used_at))}</span>` : '<span class="text-muted">Never</span>'}</td>
+              <td class="apikeys-count-cell">${count24h}</td>
+              <td class="apikeys-count-cell">${countTotal}</td>
               <td>${key.expires_at ? formatDateTime(key.expires_at) : '<span class="text-muted">Never</span>'}</td>
               <td>
                 ${key.is_active && !isExpired ? `<button class="btn-small btn-warning revoke-key-btn" data-key-id="${escapeHtml(key.id)}">Revoke</button>` : ''}
@@ -98,6 +242,11 @@ export function renderApiKeysList(): void {
     </table>
   `;
 
+  // Clear the skeleton marker before the render — the existing
+  // innerHTML write (kept intact for diff minimality) replaces all
+  // children, and we don't want a stale `data-skeleton-active`
+  // attribute lingering on the live table.
+  delete container.dataset['skeletonActive'];
   container.innerHTML = table;
 
   // Add event delegation after rendering
@@ -389,3 +538,18 @@ function showError(message: string): void {
     showToast({ message, kind: 'error' });
   }
 }
+
+/**
+ * Format a per-row request count for display in the table cells.
+ * Renders the exact integer (no abbreviation) so a row with "1,234,567"
+ * is unambiguous — the section-level summary card uses a separate
+ * `formatCount` that abbreviates large values to fit the tile width.
+ *
+ * Defends against missing fields (older cached responses without the
+ * counters from migration 000094) and non-finite inputs by coercing
+ * to 0 — never returns "undefined" or "NaN" to the rendered table.
+ */
+function formatRequestCount(n: number | undefined): string {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return '0';
+  return Math.trunc(n).toLocaleString('en-US');
+}
diff --git a/frontend/src/index.html b/frontend/src/index.html
index db8e734dd..1c659dacd 100644
--- a/frontend/src/index.html
+++ b/frontend/src/index.html
@@ -786,6 +786,9 @@ <h2>User Management</h2>
                         <div class="section-header">
                             <button type="button" id="create-apikey-btn" class="primary">Create API Key</button>
                         </div>
+                        <!-- Section-level usage summary (issue #340/#344 deferred sub-task).
+                             Populated by apikeys.ts:loadApiKeysUsageStats(). -->
+                        <div id="apikeys-usage-summary" class="mt-3"></div>
                         <div id="apikeys-list" class="mt-3"></div>
                     </fieldset>
                 </section>
diff --git a/frontend/src/styles/components.css b/frontend/src/styles/components.css
index 4454caafd..67ebba245 100644
--- a/frontend/src/styles/components.css
+++ b/frontend/src/styles/components.css
@@ -1636,3 +1636,70 @@ tr.rec-variant-row:hover td:not(.checkbox-col) {
     font-size: var(--cudly-fs-sm);
     font-style: italic;
 }
+
+/* ---------------------------------------------------------------------------
+ * API keys usage summary (issue #340/#344 deferred sub-task).
+ * Three-tile summary card + top-3 most-active list. Sits above the
+ * api-keys table inside #apikeys-section. Tiles reuse the design-token
+ * stack from .kpi-tile but stay flat (no spark-area grid) — this is a
+ * settings-page card, not a dashboard headline.
+ * ------------------------------------------------------------------------- */
+.apikeys-usage-summary {
+    padding: var(--cudly-sp-4);
+}
+
+.apikeys-usage-tiles {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+    gap: var(--cudly-sp-3);
+}
+
+.apikeys-usage-tile {
+    padding: var(--cudly-sp-3);
+    border-radius: var(--cudly-r-md);
+    border: 1px solid var(--cudly-border);
+    background: var(--cudly-bg-elevated, white);
+}
+
+.apikeys-usage-tile-label {
+    font-size: var(--cudly-fs-sm);
+    color: var(--cudly-text-muted);
+    margin-bottom: var(--cudly-sp-1);
+}
+
+.apikeys-usage-tile-value {
+    font-size: var(--cudly-fs-xl);
+    font-weight: var(--cudly-fw-semibold);
+    color: var(--cudly-text);
+}
+
+.apikeys-usage-top-heading {
+    margin: var(--cudly-sp-4) 0 var(--cudly-sp-2);
+    font-size: var(--cudly-fs-sm);
+    color: var(--cudly-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+}
+
+.apikeys-usage-top-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--cudly-sp-1);
+}
+
+.apikeys-usage-top-list li {
+    padding: var(--cudly-sp-1) 0;
+    font-size: var(--cudly-fs-sm);
+}
+
+.apikeys-usage-top-count {
+    color: var(--cudly-text-muted);
+}
+
+.apikeys-count-cell {
+    text-align: right;
+    font-variant-numeric: tabular-nums;
+}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 164e7e1d2..f94c64157 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -407,6 +407,12 @@ export interface APIKeyInfo {
   created_at: string;
   last_used_at?: string;
   permissions?: api.Permission[];
+  // Usage counters (issue #340/#344 deferred sub-task). Optional so
+  // older mock data / cached responses without the columns don't blow
+  // up the renderer -- the backend always sends them as of migration
+  // 000094.
+  request_count_total?: number;
+  request_count_24h?: number;
 }
 
 export interface CreateAPIKeyResponse {
diff --git a/internal/api/handler_apikeys.go b/internal/api/handler_apikeys.go
index f144171b8..bb31a916e 100644
--- a/internal/api/handler_apikeys.go
+++ b/internal/api/handler_apikeys.go
@@ -35,6 +35,27 @@ func (h *Handler) listAPIKeys(ctx context.Context, req *events.LambdaFunctionURL
 	return keys, nil
 }
 
+// listAPIKeysUsageStats handles GET /api/api-keys/usage-stats.
+//
+// Returns a section-level summary scoped to the calling user's own keys:
+// total active, total requests (24h + lifetime), and the top-3 keys by
+// 24h activity. Scope is identical to listAPIKeys -- both gate on the
+// same view/api-keys permission so the section header and the row list
+// can never disagree about visibility.
+func (h *Handler) listAPIKeysUsageStats(ctx context.Context, req *events.LambdaFunctionURLRequest) (any, error) {
+	session, err := h.requirePermission(ctx, req, "view", "api-keys")
+	if err != nil {
+		return nil, err
+	}
+
+	stats, err := h.auth.GetAPIKeysUsageStatsAPI(ctx, session.UserID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load API key usage stats: %w", err)
+	}
+
+	return stats, nil
+}
+
 // createAPIKey handles POST /api/api-keys.
 func (h *Handler) createAPIKey(ctx context.Context, req *events.LambdaFunctionURLRequest) (any, error) {
 	session, err := h.requirePermission(ctx, req, "create", "api-keys")
diff --git a/internal/api/handler_apikeys_test.go b/internal/api/handler_apikeys_test.go
index 05ee4d5f2..a238c4889 100644
--- a/internal/api/handler_apikeys_test.go
+++ b/internal/api/handler_apikeys_test.go
@@ -631,6 +631,93 @@ func TestHandler_revokeAPIKey_PermissionDenied(t *testing.T) {
 	mockAuth.AssertNotCalled(t, "RevokeAPIKeyAPI", mock.Anything, mock.Anything, mock.Anything)
 }
 
+// listAPIKeysUsageStats handler -- section-level summary (issue #340/#344
+// deferred sub-task). Mirrors the listAPIKeys test layout: happy path for
+// an authenticated session, a no-auth-service failure, a service-error
+// passthrough, and a permission-denied path for a caller lacking the
+// view/api-keys permission.
+
+func TestHandler_listAPIKeysUsageStats_Success(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+
+	session := &Session{UserID: "user-123", Email: "user@example.com"}
+	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
+	mockAuth.grantAdmin()
+
+	expectedStats := map[string]any{
+		"total_active":            2,
+		"total_requests_24h":      int64(15),
+		"total_requests_lifetime": int64(120),
+		"top_keys":                []map[string]any{{"id": "key-1", "name": "k1", "key_prefix": "abc12345", "request_count_24h": int64(10)}},
+	}
+	mockAuth.On("GetAPIKeysUsageStatsAPI", ctx, "user-123").Return(expectedStats, nil)
+
+	handler := &Handler{auth: mockAuth}
+
+	req := &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"Authorization": "Bearer test-token"},
+	}
+
+	result, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.NoError(t, err)
+	got, ok := result.(map[string]any)
+	require.True(t, ok)
+	assert.Equal(t, 2, got["total_active"])
+	mockAuth.AssertCalled(t, "GetAPIKeysUsageStatsAPI", ctx, "user-123")
+}
+
+func TestHandler_listAPIKeysUsageStats_NoAuthService(t *testing.T) {
+	ctx := context.Background()
+	handler := &Handler{}
+
+	req := &events.LambdaFunctionURLRequest{}
+
+	_, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "authentication service not configured")
+}
+
+func TestHandler_listAPIKeysUsageStats_ServiceError(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+
+	session := &Session{UserID: "user-123", Email: "user@example.com"}
+	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
+	mockAuth.grantAdmin()
+	mockAuth.On("GetAPIKeysUsageStatsAPI", ctx, "user-123").Return(nil, errors.New("database error"))
+
+	handler := &Handler{auth: mockAuth}
+
+	req := &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"Authorization": "Bearer test-token"},
+	}
+
+	_, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to load API key usage stats")
+}
+
+func TestHandler_listAPIKeysUsageStats_PermissionDenied(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+
+	session := &Session{UserID: "viewer-1", Email: "viewer@example.com"}
+	mockAuth.On("ValidateSession", ctx, "viewer-token").Return(session, nil)
+	mockAuth.On("HasPermissionAPI", ctx, "viewer-1", "view", "api-keys").Return(false, nil)
+
+	handler := &Handler{auth: mockAuth}
+
+	req := &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"Authorization": "Bearer viewer-token"},
+	}
+
+	_, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "permission denied")
+	mockAuth.AssertNotCalled(t, "GetAPIKeysUsageStatsAPI", mock.Anything, mock.Anything)
+}
+
 func TestFormatTimePtr(t *testing.T) {
 	t.Run("nil pointer returns empty string", func(t *testing.T) {
 		result := formatTimePtr(nil)
diff --git a/internal/api/handler_ri_exchange_test.go b/internal/api/handler_ri_exchange_test.go
index c272eb5d2..d01e44a65 100644
--- a/internal/api/handler_ri_exchange_test.go
+++ b/internal/api/handler_ri_exchange_test.go
@@ -1044,6 +1044,9 @@ func (m *mockAuthForExchange) CreateAPIKeyAPI(_ context.Context, _ string, _ any
 func (m *mockAuthForExchange) ListUserAPIKeysAPI(_ context.Context, _ string) (any, error) {
 	return nil, nil
 }
+func (m *mockAuthForExchange) GetAPIKeysUsageStatsAPI(_ context.Context, _ string) (any, error) {
+	return nil, nil
+}
 func (m *mockAuthForExchange) DeleteAPIKeyAPI(_ context.Context, _, _ string) error { return nil }
 func (m *mockAuthForExchange) RevokeAPIKeyAPI(_ context.Context, _, _ string) error { return nil }
 func (m *mockAuthForExchange) ValidateUserAPIKeyAPI(_ context.Context, _ string) (any, any, error) {
diff --git a/internal/api/mocks_test.go b/internal/api/mocks_test.go
index 5d41e12b9..03a6c163a 100644
--- a/internal/api/mocks_test.go
+++ b/internal/api/mocks_test.go
@@ -315,6 +315,11 @@ func (m *MockAuthService) ListUserAPIKeysAPI(ctx context.Context, userID string)
 	return args.Get(0), args.Error(1)
 }
 
+func (m *MockAuthService) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (interface{}, error) {
+	args := m.Called(ctx, userID)
+	return args.Get(0), args.Error(1)
+}
+
 func (m *MockAuthService) DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error {
 	args := m.Called(ctx, userID, keyID)
 	return args.Error(0)
diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index 2fd91cf70..aa2f9c401 100644
--- a/internal/api/openapi.yaml
+++ b/internal/api/openapi.yaml
@@ -1385,6 +1385,27 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
 
+  /api/api-keys/usage-stats:
+    get:
+      operationId: getAPIKeysUsageStats
+      tags: [APIKeys]
+      summary: Section-level usage summary for the caller's API keys
+      description: |
+        Aggregates per-key counters into a single summary card: number of
+        active keys, total requests (24h + lifetime), and the top-3 keys
+        by 24h request count. Scoped to the calling user's own keys.
+      responses:
+        '200':
+          description: API keys usage stats
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIKeysUsageStats'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
   /api/api-keys/{id}/revoke:
     parameters:
       - $ref: '#/components/parameters/ResourceID'
@@ -2259,6 +2280,49 @@ components:
           format: date-time
         is_active:
           type: boolean
+        request_count_total:
+          type: integer
+          format: int64
+          description: Lifetime request count since the key was created.
+        request_count_24h:
+          type: integer
+          format: int64
+          description: |
+            Rolling 24h request count. Resets when the previous window
+            crosses 24h since its first request -- the value is "requests
+            in the last 24h", not "requests today".
+
+    APIKeysUsageStats:
+      type: object
+      properties:
+        total_active:
+          type: integer
+          description: Number of currently-active API keys for the caller.
+        total_requests_24h:
+          type: integer
+          format: int64
+          description: Sum of request_count_24h across the caller's keys.
+        total_requests_lifetime:
+          type: integer
+          format: int64
+          description: Sum of request_count_total across the caller's keys.
+        top_keys:
+          type: array
+          description: |
+            Top keys by 24h request count (lifetime count as tiebreaker).
+            At most 3 entries; keys with zero 24h activity are omitted.
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              name:
+                type: string
+              key_prefix:
+                type: string
+              request_count_24h:
+                type: integer
+                format: int64
 
     # -- Configuration ------------------------------------------------------
     ConfigResponse:
diff --git a/internal/api/router.go b/internal/api/router.go
index 11d0d6a85..3388c9c66 100644
--- a/internal/api/router.go
+++ b/internal/api/router.go
@@ -241,7 +241,10 @@ func (r *Router) registerRoutes() {
 		{ExactPath: "/api/auth/mfa/disable", Method: "POST", Handler: r.mfaDisableHandler, Auth: AuthUser},
 		{ExactPath: "/api/auth/mfa/regenerate-recovery-codes", Method: "POST", Handler: r.mfaRegenerateRecoveryCodesHandler, Auth: AuthUser},
 
-		// API Key endpoints (self-service — any authenticated user)
+		// API Key endpoints (self-service — any authenticated user).
+		// Usage-stats route is declared before the generic prefix
+		// matches so the more-specific path wins.
+		{ExactPath: "/api/api-keys/usage-stats", Method: "GET", Handler: r.listAPIKeysUsageStatsHandler, Auth: AuthUser},
 		{ExactPath: "/api/api-keys", Method: "GET", Handler: r.listAPIKeysHandler, Auth: AuthUser},
 		{ExactPath: "/api/api-keys", Method: "POST", Handler: r.createAPIKeyHandler, Auth: AuthUser},
 		{PathPrefix: "/api/api-keys/", PathSuffix: "/revoke", Method: "POST", Handler: r.revokeAPIKeyHandler, Auth: AuthUser},
@@ -736,6 +739,10 @@ func (r *Router) listAPIKeysHandler(ctx context.Context, req *events.LambdaFunct
 	return r.h.listAPIKeys(ctx, req)
 }
 
+func (r *Router) listAPIKeysUsageStatsHandler(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error) {
+	return r.h.listAPIKeysUsageStats(ctx, req)
+}
+
 func (r *Router) createAPIKeyHandler(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error) {
 	return r.h.createAPIKey(ctx, req)
 }
diff --git a/internal/api/types.go b/internal/api/types.go
index b3a4dd5bb..237b0b9b7 100644
--- a/internal/api/types.go
+++ b/internal/api/types.go
@@ -208,6 +208,10 @@ type AuthServiceInterface interface {
 	// API Key management
 	CreateAPIKeyAPI(ctx context.Context, userID string, req any) (any, error)
 	ListUserAPIKeysAPI(ctx context.Context, userID string) (any, error)
+	// GetAPIKeysUsageStatsAPI returns the section-level usage summary
+	// (active count, 24h/lifetime request totals, top-3 most active
+	// keys) for the calling user's own API keys.
+	GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error)
 	DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error
 	RevokeAPIKeyAPI(ctx context.Context, userID, keyID string) error
 	ValidateUserAPIKeyAPI(ctx context.Context, apiKey string) (any, any, error)
diff --git a/internal/auth/interfaces.go b/internal/auth/interfaces.go
index 8e84c33b2..f58db2758 100644
--- a/internal/auth/interfaces.go
+++ b/internal/auth/interfaces.go
@@ -49,6 +49,11 @@ type StoreInterface interface {
 	ListAPIKeysByUser(ctx context.Context, userID string) ([]*UserAPIKey, error)
 	UpdateAPIKey(ctx context.Context, key *UserAPIKey) error
 	UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error
+	// RecordAPIKeyUsage atomically updates last_used_at and increments
+	// request_count_total + request_count_24h. The 24h counter resets
+	// (along with its window-start) when the existing window is older
+	// than 24h. See migration 000094 for the column shape.
+	RecordAPIKeyUsage(ctx context.Context, keyID string) error
 	DeleteAPIKey(ctx context.Context, keyID string) error
 
 	// Health check
diff --git a/internal/auth/service_apikeys.go b/internal/auth/service_apikeys.go
index 79a80a3a3..b7f55655e 100644
--- a/internal/auth/service_apikeys.go
+++ b/internal/auth/service_apikeys.go
@@ -283,23 +283,25 @@ func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserA
 		return nil, nil, err
 	}
 
-	// Update last used timestamp asynchronously to avoid blocking the
-	// authentication hot path. singleflight.Group ensures at most one
-	// in-flight DB write per keyID at any moment: subsequent concurrent
-	// requests for the same key are deduplicated rather than spawning an
-	// unbounded number of goroutines (DoS amplifier on a revoked key).
+	// Record usage (last_used_at + counters) asynchronously to avoid
+	// blocking the authentication hot path. singleflight.Group ensures at
+	// most one in-flight DB write per keyID at any moment: subsequent
+	// concurrent requests for the same key are deduplicated rather than
+	// spawning an unbounded number of goroutines (DoS amplifier on a
+	// revoked key). The store does an atomic single-row UPDATE -- see
+	// PostgresStore.RecordAPIKeyUsage for the rolling-24h-window logic.
 	keyID := key.ID
 	go func() {
 		if _, sfErr, _ := s.lastUsedSFG.Do(keyID, func() (any, error) {
 			defer func() {
 				if r := recover(); r != nil {
-					logging.Warnf("service_apikeys: UpdateLastUsed goroutine panic: %v", r)
+					logging.Warnf("service_apikeys: RecordUsage goroutine panic: %v", r)
 				}
 			}()
 			updateCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
-			if err := s.UpdateLastUsed(updateCtx, keyID); err != nil {
-				logging.Debugf("Failed to update API key last used timestamp for key %s: %v", keyID, err)
+			if err := s.RecordUsage(updateCtx, keyID); err != nil {
+				logging.Debugf("Failed to record API key usage for key %s: %v", keyID, err)
 			}
 			return nil, nil
 		}); sfErr != nil {
@@ -310,11 +312,20 @@ func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserA
 	return key, user, nil
 }
 
-// UpdateLastUsed updates the last used timestamp for an API key atomically.
+// UpdateLastUsed updates only the last used timestamp for an API key.
+// Retained for backwards compatibility; new code paths should use
+// RecordUsage so the request_count_* counters stay current.
 func (s *Service) UpdateLastUsed(ctx context.Context, keyID string) error {
 	return s.store.UpdateAPIKeyLastUsed(ctx, keyID)
 }
 
+// RecordUsage updates last_used_at and increments both the lifetime and
+// rolling-24h request counters for the key. See
+// PostgresStore.RecordAPIKeyUsage for the atomic SQL.
+func (s *Service) RecordUsage(ctx context.Context, keyID string) error {
+	return s.store.RecordAPIKeyUsage(ctx, keyID)
+}
+
 // computeEffectivePermissionsFromAuthCtx returns the subset of key permissions
 // that the owner's authCtx also grants at the action/resource level, keeping
 // the key's own constraint limits. If the key has no specific permissions the
diff --git a/internal/auth/service_apikeys_api.go b/internal/auth/service_apikeys_api.go
index b80876672..a9358b61b 100644
--- a/internal/auth/service_apikeys_api.go
+++ b/internal/auth/service_apikeys_api.go
@@ -4,9 +4,27 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"sort"
 	"time"
 )
 
+// apiKeyUsageTopKeysLimit caps the "most active" list returned by
+// GetAPIKeysUsageStatsAPI. Named constant per house style (no magic
+// numbers) -- kept small since the summary card is a glance-level widget.
+const apiKeyUsageTopKeysLimit = 3
+
+// sortAPIKeysByActivity sorts in place by request_count_24h desc, with
+// request_count_total desc as the tiebreaker. Extracted as a helper so
+// it can be unit-tested without going through the full service.
+func sortAPIKeysByActivity(keys []*UserAPIKey) {
+	sort.SliceStable(keys, func(i, j int) bool {
+		if keys[i].RequestCount24h != keys[j].RequestCount24h {
+			return keys[i].RequestCount24h > keys[j].RequestCount24h
+		}
+		return keys[i].RequestCountTotal > keys[j].RequestCountTotal
+	})
+}
+
 // API wrapper methods for API key operations
 // These methods return API-friendly types and handle type conversions
 
@@ -27,6 +45,29 @@ type APIKeyInfo struct {
 	KeyPrefix   string       `json:"key_prefix"`
 	Permissions []Permission `json:"permissions,omitempty"`
 	IsActive    bool         `json:"is_active"`
+	// Usage counters (issue #340/#344 deferred sub-task).
+	RequestCountTotal int64 `json:"request_count_total"`
+	RequestCount24h   int64 `json:"request_count_24h"`
+}
+
+// APIKeysUsageStatsTopKey is one entry in the top-keys list returned by
+// GetAPIKeysUsageStatsAPI. Trimmed to identifier + 24h count so the UI
+// doesn't have to re-derive anything from the full APIKeyInfo blob.
+type APIKeysUsageStatsTopKey struct {
+	ID              string `json:"id"`
+	Name            string `json:"name"`
+	KeyPrefix       string `json:"key_prefix"`
+	RequestCount24h int64  `json:"request_count_24h"`
+}
+
+// APIKeysUsageStatsResponse is the summary payload for the API keys
+// section header (issue #340/#344 deferred sub-task). Scoped to the
+// calling user's own keys -- same scope as ListUserAPIKeysAPI.
+type APIKeysUsageStatsResponse struct {
+	TotalActive           int                       `json:"total_active"`
+	TotalRequests24h      int64                     `json:"total_requests_24h"`
+	TotalRequestsLifetime int64                     `json:"total_requests_lifetime"`
+	TopKeys               []APIKeysUsageStatsTopKey `json:"top_keys"`
 }
 
 // APICreateAPIKeyResponse represents the API response for creating an API key.
@@ -79,14 +120,16 @@ func (s *Service) CreateAPIKeyAPI(ctx context.Context, userID string, req any) (
 		APIKey: apiKey,
 		KeyID:  keyInfo.ID,
 		Info: &APIKeyInfo{
-			ID:          keyInfo.ID,
-			Name:        keyInfo.Name,
-			KeyPrefix:   keyInfo.KeyPrefix,
-			Permissions: keyInfo.Permissions,
-			ExpiresAt:   keyInfo.ExpiresAt,
-			CreatedAt:   keyInfo.CreatedAt,
-			LastUsedAt:  keyInfo.LastUsedAt,
-			IsActive:    keyInfo.IsActive,
+			ID:                keyInfo.ID,
+			Name:              keyInfo.Name,
+			KeyPrefix:         keyInfo.KeyPrefix,
+			Permissions:       keyInfo.Permissions,
+			ExpiresAt:         keyInfo.ExpiresAt,
+			CreatedAt:         keyInfo.CreatedAt,
+			LastUsedAt:        keyInfo.LastUsedAt,
+			IsActive:          keyInfo.IsActive,
+			RequestCountTotal: keyInfo.RequestCountTotal,
+			RequestCount24h:   keyInfo.RequestCount24h,
 		},
 	}, nil
 }
@@ -102,14 +145,16 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 	apiKeys := make([]*APIKeyInfo, 0, len(keys))
 	for _, key := range keys {
 		apiKeys = append(apiKeys, &APIKeyInfo{
-			ID:          key.ID,
-			Name:        key.Name,
-			KeyPrefix:   key.KeyPrefix,
-			Permissions: key.Permissions,
-			ExpiresAt:   key.ExpiresAt,
-			CreatedAt:   key.CreatedAt,
-			LastUsedAt:  key.LastUsedAt,
-			IsActive:    key.IsActive,
+			ID:                key.ID,
+			Name:              key.Name,
+			KeyPrefix:         key.KeyPrefix,
+			Permissions:       key.Permissions,
+			ExpiresAt:         key.ExpiresAt,
+			CreatedAt:         key.CreatedAt,
+			LastUsedAt:        key.LastUsedAt,
+			IsActive:          key.IsActive,
+			RequestCountTotal: key.RequestCountTotal,
+			RequestCount24h:   key.RequestCount24h,
 		})
 	}
 
@@ -118,6 +163,57 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 	}, nil
 }
 
+// GetAPIKeysUsageStatsAPI computes section-level usage stats for the
+// calling user's own API keys. Aggregated in-process so we don't need a
+// separate DB round-trip -- ListUserAPIKeys already returns the per-key
+// counters from migration 000094.
+//
+// The "top keys" list is sorted by request_count_24h descending, with
+// total-lifetime as the tiebreaker so a long-running idle key doesn't
+// outrank an active one with the same 24h count. Up to
+// apiKeyUsageTopKeysLimit entries are surfaced; keys with zero 24h
+// activity are omitted rather than shown as an uninformative "top key".
+func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error) {
+	keys, err := s.ListUserAPIKeys(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+
+	resp := &APIKeysUsageStatsResponse{
+		TopKeys: []APIKeysUsageStatsTopKey{},
+	}
+	for _, k := range keys {
+		if k.IsActive {
+			resp.TotalActive++
+		}
+		resp.TotalRequests24h += k.RequestCount24h
+		resp.TotalRequestsLifetime += k.RequestCountTotal
+	}
+
+	sorted := make([]*UserAPIKey, len(keys))
+	copy(sorted, keys)
+	sortAPIKeysByActivity(sorted)
+
+	limit := apiKeyUsageTopKeysLimit
+	if len(sorted) < limit {
+		limit = len(sorted)
+	}
+	for i := 0; i < limit; i++ {
+		k := sorted[i]
+		if k.RequestCount24h == 0 {
+			break
+		}
+		resp.TopKeys = append(resp.TopKeys, APIKeysUsageStatsTopKey{
+			ID:              k.ID,
+			Name:            k.Name,
+			KeyPrefix:       k.KeyPrefix,
+			RequestCount24h: k.RequestCount24h,
+		})
+	}
+
+	return resp, nil
+}
+
 // DeleteAPIKeyAPI deletes an API key.
 func (s *Service) DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error {
 	return s.DeleteAPIKey(ctx, userID, keyID)
diff --git a/internal/auth/service_apikeys_api_test.go b/internal/auth/service_apikeys_api_test.go
index 783850a6d..cafd9dfb7 100644
--- a/internal/auth/service_apikeys_api_test.go
+++ b/internal/auth/service_apikeys_api_test.go
@@ -412,7 +412,7 @@ func TestService_ValidateUserAPIKeyAPI(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKeyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		mockStore.On("UpdateAPIKeyLastUsed", mock.Anything, "key-1").Return(nil).Maybe()
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1").Return(nil).Maybe()
 
 		resultKey, resultUser, err := service.ValidateUserAPIKeyAPI(ctx, apiKey)
 
@@ -466,3 +466,128 @@ func TestService_ValidateUserAPIKeyAPI(t *testing.T) {
 		mockStore.AssertExpectations(t)
 	})
 }
+
+func TestSortAPIKeysByActivity(t *testing.T) {
+	t.Run("sorts by 24h count descending", func(t *testing.T) {
+		keys := []*UserAPIKey{
+			{ID: "low", RequestCount24h: 1, RequestCountTotal: 100},
+			{ID: "high", RequestCount24h: 10, RequestCountTotal: 5},
+			{ID: "mid", RequestCount24h: 5, RequestCountTotal: 50},
+		}
+
+		sortAPIKeysByActivity(keys)
+
+		require.Len(t, keys, 3)
+		assert.Equal(t, "high", keys[0].ID)
+		assert.Equal(t, "mid", keys[1].ID)
+		assert.Equal(t, "low", keys[2].ID)
+	})
+
+	t.Run("uses lifetime total as tiebreaker", func(t *testing.T) {
+		keys := []*UserAPIKey{
+			{ID: "idle-high-lifetime", RequestCount24h: 3, RequestCountTotal: 900},
+			{ID: "active-low-lifetime", RequestCount24h: 3, RequestCountTotal: 10},
+		}
+
+		sortAPIKeysByActivity(keys)
+
+		require.Len(t, keys, 2)
+		assert.Equal(t, "idle-high-lifetime", keys[0].ID)
+		assert.Equal(t, "active-low-lifetime", keys[1].ID)
+	})
+}
+
+func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
+	ctx := context.Background()
+
+	t.Run("aggregates totals and returns top-3 by 24h activity", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		keys := []*UserAPIKey{
+			{ID: "key-1", Name: "Busy", KeyPrefix: "aaaa1111", IsActive: true, RequestCount24h: 30, RequestCountTotal: 300},
+			{ID: "key-2", Name: "Medium", KeyPrefix: "bbbb2222", IsActive: true, RequestCount24h: 12, RequestCountTotal: 120},
+			{ID: "key-3", Name: "Quiet", KeyPrefix: "cccc3333", IsActive: false, RequestCount24h: 3, RequestCountTotal: 60},
+			{ID: "key-4", Name: "Idle", KeyPrefix: "dddd4444", IsActive: true, RequestCount24h: 0, RequestCountTotal: 5},
+		}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		assert.Equal(t, 3, resp.TotalActive) // key-3 is inactive
+		assert.Equal(t, int64(45), resp.TotalRequests24h)
+		assert.Equal(t, int64(485), resp.TotalRequestsLifetime)
+		require.Len(t, resp.TopKeys, 3)
+		assert.Equal(t, "key-1", resp.TopKeys[0].ID)
+		assert.Equal(t, "key-2", resp.TopKeys[1].ID)
+		assert.Equal(t, "key-3", resp.TopKeys[2].ID)
+		// key-4 has zero 24h activity and must be omitted, even though the
+		// top-N slice has room for a 4th entry.
+		for _, k := range resp.TopKeys {
+			assert.NotEqual(t, "key-4", k.ID)
+		}
+	})
+
+	t.Run("omits top list entirely when no key has 24h activity", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		keys := []*UserAPIKey{
+			{ID: "key-1", IsActive: true, RequestCount24h: 0, RequestCountTotal: 7},
+		}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		assert.Equal(t, 1, resp.TotalActive)
+		assert.Equal(t, int64(0), resp.TotalRequests24h)
+		assert.Equal(t, int64(7), resp.TotalRequestsLifetime)
+		assert.Empty(t, resp.TopKeys)
+	})
+
+	t.Run("returns empty stats when user has no keys", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return([]*UserAPIKey{}, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		assert.Equal(t, 0, resp.TotalActive)
+		assert.Equal(t, int64(0), resp.TotalRequests24h)
+		assert.Equal(t, int64(0), resp.TotalRequestsLifetime)
+		assert.Empty(t, resp.TopKeys)
+	})
+
+	t.Run("propagates store error", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(nil, assert.AnError)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		assert.Error(t, err)
+		assert.Nil(t, result)
+	})
+}
diff --git a/internal/auth/service_apikeys_test.go b/internal/auth/service_apikeys_test.go
index beb142dc3..a9457190f 100644
--- a/internal/auth/service_apikeys_test.go
+++ b/internal/auth/service_apikeys_test.go
@@ -510,14 +510,24 @@ func TestService_ValidateUserAPIKey(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKeyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		mockStore.On("UpdateAPIKeyLastUsed", mock.Anything, "key-1").Return(nil).Maybe()
+		// Use a signaling channel + .Once() so the test fails (rather than
+		// silently passes) if ValidateUserAPIKey ever stops recording usage,
+		// and so we don't have to busy-sleep waiting for the async goroutine.
+		usageRecorded := make(chan struct{}, 1)
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1").
+			Run(func(mock.Arguments) { usageRecorded <- struct{}{} }).
+			Return(nil).Once()
 
 		resultKey, resultUser, err := service.ValidateUserAPIKey(ctx, apiKey)
 
 		require.NoError(t, err)
 		assert.Equal(t, user, resultUser)
 		assert.Equal(t, apiKeyRecord, resultKey)
-		time.Sleep(10 * time.Millisecond) // Allow goroutine to complete
+		select {
+		case <-usageRecorded:
+		case <-time.After(500 * time.Millisecond):
+			t.Fatal("expected RecordAPIKeyUsage to be called")
+		}
 		mockStore.AssertExpectations(t)
 	})
 
@@ -709,6 +719,32 @@ func TestService_UpdateLastUsed(t *testing.T) {
 	})
 }
 
+func TestService_RecordUsage(t *testing.T) {
+	ctx := context.Background()
+
+	t.Run("delegates to store RecordAPIKeyUsage", func(t *testing.T) {
+		mockStore := new(MockStore)
+		service := &Service{store: mockStore}
+
+		mockStore.On("RecordAPIKeyUsage", ctx, "key-1").Return(nil)
+
+		err := service.RecordUsage(ctx, "key-1")
+		require.NoError(t, err)
+		mockStore.AssertExpectations(t)
+	})
+
+	t.Run("propagates store error", func(t *testing.T) {
+		mockStore := new(MockStore)
+		service := &Service{store: mockStore}
+
+		mockStore.On("RecordAPIKeyUsage", ctx, "key-1").Return(assert.AnError)
+
+		err := service.RecordUsage(ctx, "key-1")
+		assert.Error(t, err)
+		mockStore.AssertExpectations(t)
+	})
+}
+
 func TestService_ComputeEffectivePermissions(t *testing.T) {
 	ctx := context.Background()
 
@@ -866,7 +902,7 @@ func TestService_HasAPIKeyPermissionAPI(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(keyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		mockStore.On("UpdateAPIKeyLastUsed", mock.Anything, "key-1").Return(nil).Maybe()
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1").Return(nil).Maybe()
 		mockStore.On("GetGroup", ctx, userGrpID).Return(userGrp(), nil)
 		return service
 	}
@@ -987,7 +1023,7 @@ func TestService_HasAPIKeyPermissionForConstraintsAPI_OwnerCapEnforced(t *testin
 }
 
 // TestValidateUserAPIKey_UpdateLastUsedPanicIsRecovered proves that a panic
-// inside the fire-and-forget UpdateLastUsed goroutine is caught by the
+// inside the fire-and-forget RecordUsage goroutine is caught by the
 // recover() added in issue #672. Without the recover(), the panic would crash
 // the entire test binary (an unrecovered goroutine panic terminates the
 // process). The test uses a channel -- closed by the mock Run callback just
@@ -1021,7 +1057,7 @@ func TestValidateUserAPIKey_UpdateLastUsedPanicIsRecovered(t *testing.T) {
 	// done is closed by the Run callback immediately before panicking so the
 	// test can wait for goroutine execution without time.Sleep.
 	done := make(chan struct{})
-	mockStore.On("UpdateAPIKeyLastUsed", mock.Anything, "key-panic").
+	mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-panic").
 		Run(func(args mock.Arguments) {
 			close(done)
 			panic("injected panic for #672 regression test")
diff --git a/internal/auth/service_security_test.go b/internal/auth/service_security_test.go
index 6cfa3792a..62c80b9ce 100644
--- a/internal/auth/service_security_test.go
+++ b/internal/auth/service_security_test.go
@@ -248,13 +248,13 @@ func TestValidateUserAPIKey_LastUsedSingleflight(t *testing.T) {
 		KeyPrefix: rawKey[:8],
 	}
 
-	// done is closed by the mock's Run callback when UpdateAPIKeyLastUsed is
+	// done is closed by the mock's Run callback when RecordAPIKeyUsage is
 	// invoked, confirming the background goroutine ran to completion without
 	// relying on time.Sleep.
 	done := make(chan struct{})
 	mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKey, nil).Maybe()
 	mockStore.On("GetUserByID", ctx, user.ID).Return(user, nil).Maybe()
-	mockStore.On("UpdateAPIKeyLastUsed", mock.Anything, keyID).
+	mockStore.On("RecordAPIKeyUsage", mock.Anything, keyID).
 		Run(func(args mock.Arguments) { close(done) }).
 		Return(nil).Once()
 
@@ -263,12 +263,12 @@ func TestValidateUserAPIKey_LastUsedSingleflight(t *testing.T) {
 	assert.Equal(t, keyID, gotKey.ID)
 	assert.Equal(t, user.ID, gotUser.ID)
 
-	// Wait for the background goroutine to invoke UpdateAPIKeyLastUsed.
+	// Wait for the background goroutine to invoke RecordAPIKeyUsage.
 	select {
 	case <-done:
 		// background update completed
 	case <-time.After(5 * time.Second):
-		t.Fatal("background UpdateAPIKeyLastUsed did not complete within 5s")
+		t.Fatal("background RecordAPIKeyUsage did not complete within 5s")
 	}
 }
 
diff --git a/internal/auth/store_postgres.go b/internal/auth/store_postgres.go
index d2b1cd679..4fda0f419 100644
--- a/internal/auth/store_postgres.go
+++ b/internal/auth/store_postgres.go
@@ -780,7 +780,8 @@ func (s *PostgresStore) CreateAPIKey(ctx context.Context, key *UserAPIKey) error
 func (s *PostgresStore) GetAPIKeyByID(ctx context.Context, keyID string) (*UserAPIKey, error) {
 	query := `
 		SELECT id, user_id, name, key_prefix, key_hash, permissions,
-		       is_active, expires_at, created_at, last_used_at
+		       is_active, expires_at, created_at, last_used_at,
+		       request_count_total, request_count_24h
 		FROM api_keys
 		WHERE id = $1
 	`
@@ -792,7 +793,8 @@ func (s *PostgresStore) GetAPIKeyByID(ctx context.Context, keyID string) (*UserA
 func (s *PostgresStore) GetAPIKeyByHash(ctx context.Context, keyHash string) (*UserAPIKey, error) {
 	query := `
 		SELECT id, user_id, name, key_prefix, key_hash, permissions,
-		       is_active, expires_at, created_at, last_used_at
+		       is_active, expires_at, created_at, last_used_at,
+		       request_count_total, request_count_24h
 		FROM api_keys
 		WHERE key_hash = $1 AND is_active = true
 		  AND (expires_at IS NULL OR expires_at > NOW())
@@ -805,7 +807,8 @@ func (s *PostgresStore) GetAPIKeyByHash(ctx context.Context, keyHash string) (*U
 func (s *PostgresStore) ListAPIKeysByUser(ctx context.Context, userID string) ([]*UserAPIKey, error) {
 	query := `
 		SELECT id, user_id, name, key_prefix, key_hash, permissions,
-		       is_active, expires_at, created_at, last_used_at
+		       is_active, expires_at, created_at, last_used_at,
+		       request_count_total, request_count_24h
 		FROM api_keys
 		WHERE user_id = $1
 		ORDER BY created_at DESC
@@ -870,7 +873,10 @@ func (s *PostgresStore) UpdateAPIKey(ctx context.Context, key *UserAPIKey) error
 	return nil
 }
 
-// UpdateAPIKeyLastUsed atomically updates the last_used_at timestamp for an API key.
+// UpdateAPIKeyLastUsed atomically updates the last_used_at timestamp for an
+// API key. Retained for backwards compatibility with callers that only need
+// the timestamp update -- production code routes through RecordAPIKeyUsage,
+// which additionally maintains the usage counters from migration 000094.
 func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error {
 	query := `UPDATE api_keys SET last_used_at = NOW() WHERE id = $1`
 	result, err := s.db.Exec(ctx, query, keyID)
@@ -883,6 +889,47 @@ func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string)
 	return nil
 }
 
+// RecordAPIKeyUsage atomically updates last_used_at, increments
+// request_count_total, and increments-or-resets request_count_24h based on
+// whether the rolling 24h window is still current.
+//
+// The single UPDATE does the window decision inline:
+//   - if window_start IS NULL OR (NOW() - window_start) >= 24h, start a
+//     fresh window (window_start = NOW(), count = 1).
+//   - otherwise increment the existing count.
+//
+// Doing it in one statement keeps the update atomic per row, so two
+// concurrent calls can't both see "stale window" and reset to 1 in
+// parallel -- pgx serializes updates to the same row.
+func (s *PostgresStore) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
+	query := `
+		UPDATE api_keys
+		SET last_used_at = NOW(),
+		    request_count_total = request_count_total + 1,
+		    request_count_24h = CASE
+		        WHEN request_count_24h_window_start IS NULL
+		             OR NOW() - request_count_24h_window_start >= INTERVAL '24 hours'
+		        THEN 1
+		        ELSE request_count_24h + 1
+		    END,
+		    request_count_24h_window_start = CASE
+		        WHEN request_count_24h_window_start IS NULL
+		             OR NOW() - request_count_24h_window_start >= INTERVAL '24 hours'
+		        THEN NOW()
+		        ELSE request_count_24h_window_start
+		    END
+		WHERE id = $1
+	`
+	result, err := s.db.Exec(ctx, query, keyID)
+	if err != nil {
+		return fmt.Errorf("failed to record API key usage: %w", err)
+	}
+	if result.RowsAffected() == 0 {
+		return fmt.Errorf("API key not found: %s", keyID)
+	}
+	return nil
+}
+
 // DeleteAPIKey deletes an API key.
 func (s *PostgresStore) DeleteAPIKey(ctx context.Context, keyID string) error {
 	query := `DELETE FROM api_keys WHERE id = $1`
@@ -1037,6 +1084,8 @@ func (s *PostgresStore) scanAPIKey(scanner Scanner) (*UserAPIKey, error) {
 		&expiresAt,
 		&key.CreatedAt,
 		&lastUsedAt,
+		&key.RequestCountTotal,
+		&key.RequestCount24h,
 	)
 
 	if err != nil {
diff --git a/internal/auth/store_postgres_pgxmock_test.go b/internal/auth/store_postgres_pgxmock_test.go
index 12269c7c5..499d34218 100644
--- a/internal/auth/store_postgres_pgxmock_test.go
+++ b/internal/auth/store_postgres_pgxmock_test.go
@@ -423,6 +423,7 @@ func TestPGXMock_ListUsers_RowError(t *testing.T) {
 var apiKeyColumns = []string{
 	"id", "user_id", "name", "key_prefix", "key_hash", "permissions",
 	"is_active", "expires_at", "created_at", "last_used_at",
+	"request_count_total", "request_count_24h",
 }
 
 func TestPGXMock_ListAPIKeysByUser_Success(t *testing.T) {
@@ -437,10 +438,12 @@ func TestPGXMock_ListAPIKeysByUser_Success(t *testing.T) {
 		AddRow(
 			"key-1", "user-1", "ci key", "cudly_ab", "hash-1",
 			[]byte(`[{"action":"view","resource":"recommendations"}]`), true, expires, created, lastUsed,
+			int64(42), int64(3),
 		).
 		AddRow(
 			"key-2", "user-1", "old key", "cudly_cd", "hash-2",
 			[]byte(`[]`), false, nil, created, nil,
+			int64(0), int64(0),
 		)
 
 	mock.ExpectQuery(`(?s)SELECT id, user_id, name, key_prefix, key_hash, permissions,.*FROM api_keys\s+WHERE user_id = \$1\s+ORDER BY created_at DESC`).
@@ -459,11 +462,15 @@ func TestPGXMock_ListAPIKeysByUser_Success(t *testing.T) {
 	assert.Equal(t, expires, *keys[0].ExpiresAt)
 	require.NotNil(t, keys[0].LastUsedAt)
 	assert.Equal(t, lastUsed, *keys[0].LastUsedAt)
+	assert.Equal(t, int64(42), keys[0].RequestCountTotal)
+	assert.Equal(t, int64(3), keys[0].RequestCount24h)
 
 	assert.Equal(t, "key-2", keys[1].ID)
 	assert.False(t, keys[1].IsActive)
 	assert.Nil(t, keys[1].ExpiresAt)
 	assert.Nil(t, keys[1].LastUsedAt)
+	assert.Equal(t, int64(0), keys[1].RequestCountTotal)
+	assert.Equal(t, int64(0), keys[1].RequestCount24h)
 }
 
 func TestPGXMock_ListAPIKeysByUser_QueryError(t *testing.T) {
@@ -520,6 +527,46 @@ func TestPGXMock_UpdateAPIKeyLastUsed_ExecError(t *testing.T) {
 	assert.Contains(t, err.Error(), "failed to update API key last used")
 }
 
+// ---- RecordAPIKeyUsage ----------------------------------------------------------
+
+func TestPGXMock_RecordAPIKeyUsage_Success(t *testing.T) {
+	mock := newAuthPgxMock(t)
+	store := NewPostgresStore(mock)
+
+	mock.ExpectExec(`(?s)UPDATE api_keys\s+SET last_used_at = NOW\(\),.*WHERE id = \$1`).
+		WithArgs("key-1").
+		WillReturnResult(pgxmock.NewResult("UPDATE", 1))
+
+	err := store.RecordAPIKeyUsage(context.Background(), "key-1")
+	assert.NoError(t, err)
+}
+
+func TestPGXMock_RecordAPIKeyUsage_NotFound(t *testing.T) {
+	mock := newAuthPgxMock(t)
+	store := NewPostgresStore(mock)
+
+	mock.ExpectExec(`(?s)UPDATE api_keys\s+SET last_used_at = NOW\(\),.*WHERE id = \$1`).
+		WithArgs("missing-key").
+		WillReturnResult(pgxmock.NewResult("UPDATE", 0))
+
+	err := store.RecordAPIKeyUsage(context.Background(), "missing-key")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "API key not found")
+}
+
+func TestPGXMock_RecordAPIKeyUsage_ExecError(t *testing.T) {
+	mock := newAuthPgxMock(t)
+	store := NewPostgresStore(mock)
+
+	mock.ExpectExec(`(?s)UPDATE api_keys\s+SET last_used_at = NOW\(\),.*WHERE id = \$1`).
+		WithArgs("key-1").
+		WillReturnError(errors.New("db down"))
+
+	err := store.RecordAPIKeyUsage(context.Background(), "key-1")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to record API key usage")
+}
+
 // ---- Ping ----------------------------------------------------------------------
 
 func TestPGXMock_Ping(t *testing.T) {
diff --git a/internal/auth/test_helpers.go b/internal/auth/test_helpers.go
index dd913a13c..fdf53452a 100644
--- a/internal/auth/test_helpers.go
+++ b/internal/auth/test_helpers.go
@@ -217,6 +217,11 @@ func (m *MockStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) erro
 	return args.Error(0)
 }
 
+func (m *MockStore) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
+	args := m.Called(ctx, keyID)
+	return args.Error(0)
+}
+
 func (m *MockStore) DeleteAPIKey(ctx context.Context, keyID string) error {
 	args := m.Called(ctx, keyID)
 	return args.Error(0)
diff --git a/internal/auth/types.go b/internal/auth/types.go
index 778cfb2d9..c84e81db3 100644
--- a/internal/auth/types.go
+++ b/internal/auth/types.go
@@ -78,6 +78,12 @@ type UserAPIKey struct {
 	KeyHash     string       `json:"-" dynamodbav:"KeyHash"`
 	Permissions []Permission `json:"permissions,omitempty" dynamodbav:"Permissions"`
 	IsActive    bool         `json:"is_active" dynamodbav:"IsActive"`
+	// Usage counters (issue #340/#344 deferred sub-task -- migration 000094).
+	// Both default to 0 for legacy rows. RequestCount24h is reset by the
+	// store's RecordAPIKeyUsage path once its window-start is older than
+	// 24h, so it really is a "last 24h" number, not "last calendar day".
+	RequestCountTotal int64 `json:"request_count_total" dynamodbav:"RequestCountTotal"`
+	RequestCount24h   int64 `json:"request_count_24h" dynamodbav:"RequestCount24h"`
 }
 
 // AuthContext represents the complete authorization context for a user
diff --git a/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
new file mode 100644
index 000000000..d6c284e15
--- /dev/null
+++ b/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
@@ -0,0 +1,5 @@
+-- Roll back API key usage counters (000094).
+ALTER TABLE api_keys
+    DROP COLUMN IF EXISTS request_count_24h_window_start,
+    DROP COLUMN IF EXISTS request_count_24h,
+    DROP COLUMN IF EXISTS request_count_total;
diff --git a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
new file mode 100644
index 000000000..5e4a45003
--- /dev/null
+++ b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
@@ -0,0 +1,25 @@
+-- API key usage counters (deferred sub-task from #340 / #344).
+--
+-- Surface per-key request volume to the Admin -> API Keys UI without
+-- introducing a separate audit-log table. Two counters live directly on
+-- the api_keys row, updated atomically by the same code path that
+-- already maintains last_used_at:
+--
+--   * request_count_total       -- lifetime count since the key was created.
+--   * request_count_24h         -- rolling 24-hour count; reset by the
+--                                 increment path once the window age
+--                                 crosses 24h (see store_postgres.go
+--                                 RecordAPIKeyUsage).
+--   * request_count_24h_window_start -- the timestamp the current 24h
+--                                 window started at; NULL until the
+--                                 first request after this migration
+--                                 runs.
+--
+-- Counters default to 0 so all existing rows show "0 requests" rather
+-- than "(null)" in the UI. The window-start column is nullable because
+-- a row with zero-ever-usage shouldn't lie about when its window began.
+
+ALTER TABLE api_keys
+    ADD COLUMN IF NOT EXISTS request_count_total BIGINT NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS request_count_24h BIGINT NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS request_count_24h_window_start TIMESTAMPTZ;
diff --git a/internal/mocks/stores.go b/internal/mocks/stores.go
index a2cecdd41..0cc4ccd43 100644
--- a/internal/mocks/stores.go
+++ b/internal/mocks/stores.go
@@ -818,6 +818,12 @@ func (m *MockAuthStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string)
 	return args.Error(0)
 }
 
+// RecordAPIKeyUsage mocks the RecordAPIKeyUsage operation.
+func (m *MockAuthStore) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
+	args := m.Called(ctx, keyID)
+	return args.Error(0)
+}
+
 // DeleteAPIKey mocks the DeleteAPIKey operation.
 func (m *MockAuthStore) DeleteAPIKey(ctx context.Context, keyID string) error {
 	args := m.Called(ctx, keyID)
diff --git a/internal/server/app.go b/internal/server/app.go
index 975bc0770..b93f7405f 100644
--- a/internal/server/app.go
+++ b/internal/server/app.go
@@ -1178,6 +1178,10 @@ func (a *authServiceAdapter) ListUserAPIKeysAPI(ctx context.Context, userID stri
 	return a.service.ListUserAPIKeysAPI(ctx, userID)
 }
 
+func (a *authServiceAdapter) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error) {
+	return a.service.GetAPIKeysUsageStatsAPI(ctx, userID)
+}
+
 func (a *authServiceAdapter) DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error {
 	return a.service.DeleteAPIKeyAPI(ctx, userID, keyID)
 }
diff --git a/internal/server/health_test.go b/internal/server/health_test.go
index 74d86b970..87e793c1b 100644
--- a/internal/server/health_test.go
+++ b/internal/server/health_test.go
@@ -120,6 +120,10 @@ func (m *mockAuthStoreForHealth) UpdateAPIKeyLastUsed(ctx context.Context, keyID
 	return nil
 }
 
+func (m *mockAuthStoreForHealth) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
+	return nil
+}
+
 func (m *mockAuthStoreForHealth) DeleteAPIKey(ctx context.Context, keyID string) error {
 	return nil
 }

From 4c2be87ca1fe348e01ebfae605856148d0bbb415 Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 18:16:28 +0200
Subject: [PATCH 2/8] fix(auth+api+frontend): correct API-key usage-window
 naming, extract oversized files, fix migration gap

CodeRabbit findings on PR #1523:

- request_count_24h was a fixed/tumbling window counter, not a true
  rolling 24h total (a request just before a window reset was silently
  dropped from the count). Renamed to request_count_window across the
  DB column, Go types, OpenAPI schema, and frontend, and exposed the new
  request_count_window_start field so API consumers can see exactly
  which period the count covers instead of assuming "last 24h".
- Split the new usage-stats rendering out of frontend/src/apikeys.ts
  into frontend/src/apikeys_usage.ts, bringing apikeys.ts back under
  the 500-line limit.
- Split the new usage-stats handler and its router wrapper out of
  internal/api/handler_apikeys.go / router.go into a focused
  internal/api/handler_apikeys_usage.go (tests moved alongside into
  handler_apikeys_usage_test.go).

Also fixes the failing Integration Tests job: migration 000094 left a
numbering gap after 000092 (000093 was skipped), so
TestMigrations_AutoHealDirty's rollback-lands-one-version-below-head
assertion failed -- rolling back landed on 92, not 93, since no
migration owns that version. Renumbered the migration to 000093 to
close the gap.
---
 frontend/src/__tests__/api-apikeys.test.ts    |   4 +-
 frontend/src/__tests__/apikeys.test.ts        |  26 ++--
 frontend/src/api/types.ts                     |  12 +-
 frontend/src/apikeys.ts                       | 123 ++---------------
 frontend/src/apikeys_usage.ts                 | 124 ++++++++++++++++++
 frontend/src/types.ts                         |   7 +-
 internal/api/handler_apikeys.go               |  21 ---
 internal/api/handler_apikeys_test.go          |  89 +------------
 internal/api/handler_apikeys_usage.go         |  42 ++++++
 internal/api/handler_apikeys_usage_test.go    |  99 ++++++++++++++
 internal/api/openapi.yaml                     |  34 +++--
 internal/api/router.go                        |   6 +-
 internal/api/types.go                         |   4 +-
 internal/auth/interfaces.go                   |   7 +-
 internal/auth/service_apikeys.go              |   9 +-
 internal/auth/service_apikeys_api.go          | 112 +++++++++-------
 internal/auth/service_apikeys_api_test.go     |  34 ++---
 internal/auth/store_postgres.go               |  50 ++++---
 internal/auth/store_postgres_pgxmock_test.go  |  14 +-
 internal/auth/types.go                        |  18 ++-
 .../000093_api_keys_usage_counters.down.sql   |   5 +
 .../000093_api_keys_usage_counters.up.sql     |  33 +++++
 .../000094_api_keys_usage_counters.down.sql   |   5 -
 .../000094_api_keys_usage_counters.up.sql     |  25 ----
 24 files changed, 514 insertions(+), 389 deletions(-)
 create mode 100644 frontend/src/apikeys_usage.ts
 create mode 100644 internal/api/handler_apikeys_usage.go
 create mode 100644 internal/api/handler_apikeys_usage_test.go
 create mode 100644 internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql
 create mode 100644 internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
 delete mode 100644 internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
 delete mode 100644 internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql

diff --git a/frontend/src/__tests__/api-apikeys.test.ts b/frontend/src/__tests__/api-apikeys.test.ts
index 960d2752d..ef38a9a89 100644
--- a/frontend/src/__tests__/api-apikeys.test.ts
+++ b/frontend/src/__tests__/api-apikeys.test.ts
@@ -61,10 +61,10 @@ describe('API Keys API Module', () => {
     test('fetches section-level usage summary', async () => {
       const mockResponse = {
         total_active: 2,
-        total_requests_24h: 42,
+        total_requests_window: 42,
         total_requests_lifetime: 1234,
         top_keys: [
-          { id: 'key-1', name: 'Busy', key_prefix: 'abc12345', request_count_24h: 30 },
+          { id: 'key-1', name: 'Busy', key_prefix: 'abc12345', request_count_window: 30 },
         ],
       };
 
diff --git a/frontend/src/__tests__/apikeys.test.ts b/frontend/src/__tests__/apikeys.test.ts
index ec3b94401..4966289d8 100644
--- a/frontend/src/__tests__/apikeys.test.ts
+++ b/frontend/src/__tests__/apikeys.test.ts
@@ -66,7 +66,7 @@ describe('API Keys Module', () => {
     // only set up `getApiKeys`. Individual tests can override.
     (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
       total_active: 0,
-      total_requests_24h: 0,
+      total_requests_window: 0,
       total_requests_lifetime: 0,
       top_keys: [],
     });
@@ -1019,11 +1019,11 @@ describe('API Keys Module', () => {
       (api.getApiKeys as jest.Mock).mockResolvedValue({ api_keys: [] });
       (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
         total_active: 2,
-        total_requests_24h: 42,
+        total_requests_window: 42,
         total_requests_lifetime: 1234,
         top_keys: [
-          { id: 'key-1', name: 'Busy', key_prefix: 'aaaa1111', request_count_24h: 30 },
-          { id: 'key-2', name: 'Medium', key_prefix: 'bbbb2222', request_count_24h: 12 },
+          { id: 'key-1', name: 'Busy', key_prefix: 'aaaa1111', request_count_window: 30 },
+          { id: 'key-2', name: 'Medium', key_prefix: 'bbbb2222', request_count_window: 12 },
         ],
       });
 
@@ -1034,22 +1034,22 @@ describe('API Keys Module', () => {
       const summary = document.getElementById('apikeys-usage-summary');
       expect(summary?.textContent).toContain('Active keys');
       expect(summary?.textContent).toContain('2');
-      expect(summary?.textContent).toContain('Requests (24h)');
+      expect(summary?.textContent).toContain('Requests (window)');
       expect(summary?.textContent).toContain('42');
       expect(summary?.textContent).toContain('Requests (lifetime)');
       // formatCount abbreviates large numbers in the summary tiles to
       // fit the tile width — table cells keep the exact integer.
       expect(summary?.textContent).toContain('1.2k');
-      expect(summary?.textContent).toContain('Most active (24h)');
+      expect(summary?.textContent).toContain('Most active (window)');
       expect(summary?.textContent).toContain('Busy');
       expect(summary?.textContent).toContain('aaaa1111');
     });
 
-    test('omits top-list when no key has 24h activity', async () => {
+    test('omits top-list when no key has window activity', async () => {
       (api.getApiKeys as jest.Mock).mockResolvedValue({ api_keys: [] });
       (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
         total_active: 1,
-        total_requests_24h: 0,
+        total_requests_window: 0,
         total_requests_lifetime: 7,
         top_keys: [],
       });
@@ -1058,7 +1058,7 @@ describe('API Keys Module', () => {
       await new Promise((r) => setTimeout(r, 0));
 
       const summary = document.getElementById('apikeys-usage-summary');
-      expect(summary?.textContent).not.toContain('Most active (24h)');
+      expect(summary?.textContent).not.toContain('Most active (window)');
     });
 
     test('shows inline error when stats endpoint fails, table still renders', async () => {
@@ -1079,7 +1079,7 @@ describe('API Keys Module', () => {
       expect(list?.innerHTML).toContain('abc12345');
     });
 
-    test('renders Requests (24h) and Requests (total) columns per row', async () => {
+    test('renders Requests (window) and Requests (total) columns per row', async () => {
       (api.getApiKeys as jest.Mock).mockResolvedValue({
         api_keys: [
           {
@@ -1088,7 +1088,7 @@ describe('API Keys Module', () => {
             key_prefix: 'abc12345',
             is_active: true,
             created_at: '2024-01-15T10:00:00Z',
-            request_count_24h: 12,
+            request_count_window: 12,
             request_count_total: 1234,
           },
         ],
@@ -1097,7 +1097,7 @@ describe('API Keys Module', () => {
       await loadApiKeys();
 
       const container = document.getElementById('apikeys-list');
-      expect(container?.innerHTML).toContain('Requests (24h)');
+      expect(container?.innerHTML).toContain('Requests (window)');
       expect(container?.innerHTML).toContain('Requests (total)');
       // Counts render with thousands separator for readability.
       expect(container?.innerHTML).toContain('1,234');
@@ -1125,7 +1125,7 @@ describe('API Keys Module', () => {
       (api.getApiKeys as jest.Mock).mockRejectedValue(new Error('list boom'));
       (api.getApiKeysUsageStats as jest.Mock).mockResolvedValue({
         total_active: 0,
-        total_requests_24h: 0,
+        total_requests_window: 0,
         total_requests_lifetime: 0,
         top_keys: [],
       });
diff --git a/frontend/src/api/types.ts b/frontend/src/api/types.ts
index 4ce65be5f..71844b9f0 100644
--- a/frontend/src/api/types.ts
+++ b/frontend/src/api/types.ts
@@ -578,21 +578,25 @@ export interface APIKeyInfo {
   // Usage counters (issue #340/#344 deferred sub-task).
   // Optional in the type so older mock data / cached responses without
   // the columns don't blow up the renderer -- but the backend always
-  // sends them as of migration 000094.
+  // sends them as of migration 000093. request_count_window is a
+  // FIXED/TUMBLING window count, not a true rolling 24h total --
+  // request_count_window_start says exactly which period it covers.
   request_count_total?: number;
-  request_count_24h?: number;
+  request_count_window?: number;
+  request_count_window_start?: string;
 }
 
 export interface APIKeysUsageStatsTopKey {
   id: string;
   name: string;
   key_prefix: string;
-  request_count_24h: number;
+  request_count_window: number;
 }
 
 export interface APIKeysUsageStats {
   total_active: number;
-  total_requests_24h: number;
+  // Sum of each key's fixed-window counter -- not a true rolling 24h total.
+  total_requests_window: number;
   total_requests_lifetime: number;
   top_keys: APIKeysUsageStatsTopKey[];
 }
diff --git a/frontend/src/apikeys.ts b/frontend/src/apikeys.ts
index f40e38255..622692839 100644
--- a/frontend/src/apikeys.ts
+++ b/frontend/src/apikeys.ts
@@ -4,12 +4,12 @@
 
 import * as api from './api';
 import type { APIKeyInfo, CreateAPIKeyResponse } from './types';
-import type { APIKeysUsageStats } from './api/types';
+import { loadApiKeysUsageStats } from './apikeys_usage';
 import { escapeHtml, formatDateTime, formatRelativeTime } from './utils';
 import { confirmDialog } from './confirmDialog';
 import { showToast } from './toast';
 import { openModal, closeModal } from './modal';
-import { showSkeletonRows, showSkeletonBlock, teardownSkeleton } from './lib/skeleton';
+import { showSkeletonRows, teardownSkeleton } from './lib/skeleton';
 
 // State for modal management
 let currentApiKeys: APIKeyInfo[] = [];
@@ -68,112 +68,6 @@ function renderApiKeysListError(container: HTMLElement | null, message: string):
   container.appendChild(p);
 }
 
-/**
- * Load and render the section-level usage summary (totals + top keys).
- * Fails closed: on error the summary slot shows an inline message and
- * the rest of the section still works.
- */
-export async function loadApiKeysUsageStats(): Promise<void> {
-  const container = document.getElementById('apikeys-usage-summary');
-  if (!container) return;
-  showSkeletonBlock(container, '100%', '4rem');
-  try {
-    const stats = await api.getApiKeysUsageStats();
-    renderApiKeysUsageSummary(stats);
-  } catch (error) {
-    console.error('Failed to load API keys usage stats:', error);
-    teardownSkeleton(container);
-    const p = document.createElement('p');
-    p.className = 'error';
-    p.textContent = 'Failed to load usage summary';
-    container.appendChild(p);
-  }
-}
-
-/**
- * Render the section-level summary card: total active keys, total
- * requests (24h + lifetime), and a top-3 most-active row. Built with
- * createElement only (no innerHTML) to match the codebase XSS posture.
- */
-export function renderApiKeysUsageSummary(stats: APIKeysUsageStats): void {
-  const container = document.getElementById('apikeys-usage-summary');
-  if (!container) return;
-  container.replaceChildren();
-  delete container.dataset['skeletonActive'];
-
-  const card = document.createElement('div');
-  card.className = 'apikeys-usage-summary card';
-
-  const tiles = document.createElement('div');
-  tiles.className = 'apikeys-usage-tiles';
-  tiles.appendChild(buildSummaryTile('Active keys', String(stats.total_active)));
-  tiles.appendChild(buildSummaryTile('Requests (24h)', formatCount(stats.total_requests_24h)));
-  tiles.appendChild(buildSummaryTile('Requests (lifetime)', formatCount(stats.total_requests_lifetime)));
-  card.appendChild(tiles);
-
-  if (stats.top_keys && stats.top_keys.length > 0) {
-    const heading = document.createElement('h5');
-    heading.className = 'apikeys-usage-top-heading';
-    heading.textContent = 'Most active (24h)';
-    card.appendChild(heading);
-
-    const list = document.createElement('ul');
-    list.className = 'apikeys-usage-top-list';
-    for (const top of stats.top_keys) {
-      const li = document.createElement('li');
-      const name = document.createElement('strong');
-      name.textContent = top.name;
-      const code = document.createElement('code');
-      code.textContent = `${top.key_prefix}...`;
-      const count = document.createElement('span');
-      count.className = 'apikeys-usage-top-count';
-      count.textContent = `${formatCount(top.request_count_24h)} req`;
-      li.appendChild(name);
-      li.appendChild(document.createTextNode(' '));
-      li.appendChild(code);
-      li.appendChild(document.createTextNode(' — '));
-      li.appendChild(count);
-      list.appendChild(li);
-    }
-    card.appendChild(list);
-  }
-
-  container.appendChild(card);
-}
-
-function buildSummaryTile(label: string, value: string): HTMLElement {
-  const tile = document.createElement('div');
-  tile.className = 'apikeys-usage-tile';
-  const labelEl = document.createElement('div');
-  labelEl.className = 'apikeys-usage-tile-label';
-  labelEl.textContent = label;
-  const valueEl = document.createElement('div');
-  valueEl.className = 'apikeys-usage-tile-value';
-  valueEl.textContent = value;
-  tile.appendChild(labelEl);
-  tile.appendChild(valueEl);
-  return tile;
-}
-
-/**
- * Format a request count for display in the summary tiles. Uses the
- * standard "k" / "M" abbreviation for large values so the tile doesn't
- * have to fit "1,234,567" -- the per-row table cells still show the
- * exact number via formatRequestCount.
- */
-function formatCount(n: number): string {
-  if (!Number.isFinite(n) || n < 0) return '0';
-  if (n < 1000) return String(Math.trunc(n));
-  if (n < 1_000_000) {
-    // Round to the chosen precision FIRST so we can detect the
-    // 999,500..999,999 band that rounds up to 1000k and promote
-    // it to the M branch instead of emitting "1000k".
-    const k = Number((n / 1000).toFixed(n < 10_000 ? 1 : 0));
-    if (k < 1000) return `${k}k`;
-  }
-  return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 1 : 0)}M`;
-}
-
 /**
  * Render API keys list
  */
@@ -207,7 +101,7 @@ export function renderApiKeysList(): void {
           <th>Status</th>
           <th>Created</th>
           <th>Last Used</th>
-          <th>Requests (24h)</th>
+          <th>Requests (window)</th>
           <th>Requests (total)</th>
           <th>Expires</th>
           <th>Actions</th>
@@ -218,7 +112,7 @@ export function renderApiKeysList(): void {
           const isExpired = key.expires_at && new Date(key.expires_at) < new Date();
           const statusClass = !key.is_active ? 'badge-danger' : isExpired ? 'badge-warning' : 'badge-success';
           const statusText = !key.is_active ? 'Revoked' : isExpired ? 'Expired' : 'Active';
-          const count24h = formatRequestCount(key.request_count_24h);
+          const countWindow = formatRequestCount(key.request_count_window);
           const countTotal = formatRequestCount(key.request_count_total);
 
           return `
@@ -228,7 +122,7 @@ export function renderApiKeysList(): void {
               <td><span class="badge ${statusClass}">${statusText}</span></td>
               <td>${formatDateTime(key.created_at)}</td>
               <td>${key.last_used_at ? `<span title="${escapeHtml(new Date(key.last_used_at).toISOString())}">${escapeHtml(formatRelativeTime(key.last_used_at))}</span>` : '<span class="text-muted">Never</span>'}</td>
-              <td class="apikeys-count-cell">${count24h}</td>
+              <td class="apikeys-count-cell">${countWindow}</td>
               <td class="apikeys-count-cell">${countTotal}</td>
               <td>${key.expires_at ? formatDateTime(key.expires_at) : '<span class="text-muted">Never</span>'}</td>
               <td>
@@ -542,11 +436,12 @@ function showError(message: string): void {
 /**
  * Format a per-row request count for display in the table cells.
  * Renders the exact integer (no abbreviation) so a row with "1,234,567"
- * is unambiguous — the section-level summary card uses a separate
- * `formatCount` that abbreviates large values to fit the tile width.
+ * is unambiguous — the section-level summary card in apikeys_usage.ts
+ * uses a separate `formatCount` that abbreviates large values to fit
+ * the tile width.
  *
  * Defends against missing fields (older cached responses without the
- * counters from migration 000094) and non-finite inputs by coercing
+ * counters from migration 000093) and non-finite inputs by coercing
  * to 0 — never returns "undefined" or "NaN" to the rendered table.
  */
 function formatRequestCount(n: number | undefined): string {
diff --git a/frontend/src/apikeys_usage.ts b/frontend/src/apikeys_usage.ts
new file mode 100644
index 000000000..3b412f419
--- /dev/null
+++ b/frontend/src/apikeys_usage.ts
@@ -0,0 +1,124 @@
+/**
+ * API Keys usage-stats summary module for CUDly.
+ *
+ * Split out of apikeys.ts (CodeRabbit finding on PR #1523 -- apikeys.ts
+ * exceeded the 500-line limit once the usage-summary rendering was added).
+ * This module owns the section-level summary card above the API keys
+ * table: loading, rendering, and formatting for total-active / requests
+ * (window + lifetime) / top-3-most-active.
+ */
+
+import * as api from './api';
+import type { APIKeysUsageStats } from './api/types';
+import { showSkeletonBlock, teardownSkeleton } from './lib/skeleton';
+
+/**
+ * Load and render the section-level usage summary (totals + top keys).
+ * Fails closed: on error the summary slot shows an inline message and
+ * the rest of the section still works.
+ */
+export async function loadApiKeysUsageStats(): Promise<void> {
+  const container = document.getElementById('apikeys-usage-summary');
+  if (!container) return;
+  showSkeletonBlock(container, '100%', '4rem');
+  try {
+    const stats = await api.getApiKeysUsageStats();
+    renderApiKeysUsageSummary(stats);
+  } catch (error) {
+    console.error('Failed to load API keys usage stats:', error);
+    teardownSkeleton(container);
+    const p = document.createElement('p');
+    p.className = 'error';
+    p.textContent = 'Failed to load usage summary';
+    container.appendChild(p);
+  }
+}
+
+/**
+ * Render the section-level summary card: total active keys, total
+ * requests (current window + lifetime), and a top-3 most-active row.
+ * Built with createElement only (no innerHTML) to match the codebase
+ * XSS posture.
+ *
+ * "Requests (window)" reflects request_count_window, a FIXED/TUMBLING
+ * window count (not a true rolling 24h total) -- see
+ * APIKeysUsageStats.total_requests_window.
+ */
+export function renderApiKeysUsageSummary(stats: APIKeysUsageStats): void {
+  const container = document.getElementById('apikeys-usage-summary');
+  if (!container) return;
+  container.replaceChildren();
+  delete container.dataset['skeletonActive'];
+
+  const card = document.createElement('div');
+  card.className = 'apikeys-usage-summary card';
+
+  const tiles = document.createElement('div');
+  tiles.className = 'apikeys-usage-tiles';
+  tiles.appendChild(buildSummaryTile('Active keys', String(stats.total_active)));
+  tiles.appendChild(buildSummaryTile('Requests (window)', formatCount(stats.total_requests_window)));
+  tiles.appendChild(buildSummaryTile('Requests (lifetime)', formatCount(stats.total_requests_lifetime)));
+  card.appendChild(tiles);
+
+  if (stats.top_keys && stats.top_keys.length > 0) {
+    const heading = document.createElement('h5');
+    heading.className = 'apikeys-usage-top-heading';
+    heading.textContent = 'Most active (window)';
+    card.appendChild(heading);
+
+    const list = document.createElement('ul');
+    list.className = 'apikeys-usage-top-list';
+    for (const top of stats.top_keys) {
+      const li = document.createElement('li');
+      const name = document.createElement('strong');
+      name.textContent = top.name;
+      const code = document.createElement('code');
+      code.textContent = `${top.key_prefix}...`;
+      const count = document.createElement('span');
+      count.className = 'apikeys-usage-top-count';
+      count.textContent = `${formatCount(top.request_count_window)} req`;
+      li.appendChild(name);
+      li.appendChild(document.createTextNode(' '));
+      li.appendChild(code);
+      li.appendChild(document.createTextNode(' — '));
+      li.appendChild(count);
+      list.appendChild(li);
+    }
+    card.appendChild(list);
+  }
+
+  container.appendChild(card);
+}
+
+function buildSummaryTile(label: string, value: string): HTMLElement {
+  const tile = document.createElement('div');
+  tile.className = 'apikeys-usage-tile';
+  const labelEl = document.createElement('div');
+  labelEl.className = 'apikeys-usage-tile-label';
+  labelEl.textContent = label;
+  const valueEl = document.createElement('div');
+  valueEl.className = 'apikeys-usage-tile-value';
+  valueEl.textContent = value;
+  tile.appendChild(labelEl);
+  tile.appendChild(valueEl);
+  return tile;
+}
+
+/**
+ * Format a request count for display in the summary tiles. Uses the
+ * standard "k" / "M" abbreviation for large values so the tile doesn't
+ * have to fit "1,234,567" -- the per-row table cells still show the
+ * exact number via apikeys.ts's formatRequestCount.
+ */
+function formatCount(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return '0';
+  if (n < 1000) return String(Math.trunc(n));
+  if (n < 1_000_000) {
+    // Round to the chosen precision FIRST so we can detect the
+    // 999,500..999,999 band that rounds up to 1000k and promote
+    // it to the M branch instead of emitting "1000k".
+    const k = Number((n / 1000).toFixed(n < 10_000 ? 1 : 0));
+    if (k < 1000) return `${k}k`;
+  }
+  return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 1 : 0)}M`;
+}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index f94c64157..949469171 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -410,9 +410,12 @@ export interface APIKeyInfo {
   // Usage counters (issue #340/#344 deferred sub-task). Optional so
   // older mock data / cached responses without the columns don't blow
   // up the renderer -- the backend always sends them as of migration
-  // 000094.
+  // 000093. request_count_window is a FIXED/TUMBLING window count, not
+  // a true rolling 24h total -- request_count_window_start says exactly
+  // which period it covers.
   request_count_total?: number;
-  request_count_24h?: number;
+  request_count_window?: number;
+  request_count_window_start?: string;
 }
 
 export interface CreateAPIKeyResponse {
diff --git a/internal/api/handler_apikeys.go b/internal/api/handler_apikeys.go
index bb31a916e..f144171b8 100644
--- a/internal/api/handler_apikeys.go
+++ b/internal/api/handler_apikeys.go
@@ -35,27 +35,6 @@ func (h *Handler) listAPIKeys(ctx context.Context, req *events.LambdaFunctionURL
 	return keys, nil
 }
 
-// listAPIKeysUsageStats handles GET /api/api-keys/usage-stats.
-//
-// Returns a section-level summary scoped to the calling user's own keys:
-// total active, total requests (24h + lifetime), and the top-3 keys by
-// 24h activity. Scope is identical to listAPIKeys -- both gate on the
-// same view/api-keys permission so the section header and the row list
-// can never disagree about visibility.
-func (h *Handler) listAPIKeysUsageStats(ctx context.Context, req *events.LambdaFunctionURLRequest) (any, error) {
-	session, err := h.requirePermission(ctx, req, "view", "api-keys")
-	if err != nil {
-		return nil, err
-	}
-
-	stats, err := h.auth.GetAPIKeysUsageStatsAPI(ctx, session.UserID)
-	if err != nil {
-		return nil, fmt.Errorf("failed to load API key usage stats: %w", err)
-	}
-
-	return stats, nil
-}
-
 // createAPIKey handles POST /api/api-keys.
 func (h *Handler) createAPIKey(ctx context.Context, req *events.LambdaFunctionURLRequest) (any, error) {
 	session, err := h.requirePermission(ctx, req, "create", "api-keys")
diff --git a/internal/api/handler_apikeys_test.go b/internal/api/handler_apikeys_test.go
index a238c4889..ed4c8ff6a 100644
--- a/internal/api/handler_apikeys_test.go
+++ b/internal/api/handler_apikeys_test.go
@@ -631,92 +631,9 @@ func TestHandler_revokeAPIKey_PermissionDenied(t *testing.T) {
 	mockAuth.AssertNotCalled(t, "RevokeAPIKeyAPI", mock.Anything, mock.Anything, mock.Anything)
 }
 
-// listAPIKeysUsageStats handler -- section-level summary (issue #340/#344
-// deferred sub-task). Mirrors the listAPIKeys test layout: happy path for
-// an authenticated session, a no-auth-service failure, a service-error
-// passthrough, and a permission-denied path for a caller lacking the
-// view/api-keys permission.
-
-func TestHandler_listAPIKeysUsageStats_Success(t *testing.T) {
-	ctx := context.Background()
-	mockAuth := new(MockAuthService)
-
-	session := &Session{UserID: "user-123", Email: "user@example.com"}
-	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
-	mockAuth.grantAdmin()
-
-	expectedStats := map[string]any{
-		"total_active":            2,
-		"total_requests_24h":      int64(15),
-		"total_requests_lifetime": int64(120),
-		"top_keys":                []map[string]any{{"id": "key-1", "name": "k1", "key_prefix": "abc12345", "request_count_24h": int64(10)}},
-	}
-	mockAuth.On("GetAPIKeysUsageStatsAPI", ctx, "user-123").Return(expectedStats, nil)
-
-	handler := &Handler{auth: mockAuth}
-
-	req := &events.LambdaFunctionURLRequest{
-		Headers: map[string]string{"Authorization": "Bearer test-token"},
-	}
-
-	result, err := handler.listAPIKeysUsageStats(ctx, req)
-	require.NoError(t, err)
-	got, ok := result.(map[string]any)
-	require.True(t, ok)
-	assert.Equal(t, 2, got["total_active"])
-	mockAuth.AssertCalled(t, "GetAPIKeysUsageStatsAPI", ctx, "user-123")
-}
-
-func TestHandler_listAPIKeysUsageStats_NoAuthService(t *testing.T) {
-	ctx := context.Background()
-	handler := &Handler{}
-
-	req := &events.LambdaFunctionURLRequest{}
-
-	_, err := handler.listAPIKeysUsageStats(ctx, req)
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), "authentication service not configured")
-}
-
-func TestHandler_listAPIKeysUsageStats_ServiceError(t *testing.T) {
-	ctx := context.Background()
-	mockAuth := new(MockAuthService)
-
-	session := &Session{UserID: "user-123", Email: "user@example.com"}
-	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
-	mockAuth.grantAdmin()
-	mockAuth.On("GetAPIKeysUsageStatsAPI", ctx, "user-123").Return(nil, errors.New("database error"))
-
-	handler := &Handler{auth: mockAuth}
-
-	req := &events.LambdaFunctionURLRequest{
-		Headers: map[string]string{"Authorization": "Bearer test-token"},
-	}
-
-	_, err := handler.listAPIKeysUsageStats(ctx, req)
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), "failed to load API key usage stats")
-}
-
-func TestHandler_listAPIKeysUsageStats_PermissionDenied(t *testing.T) {
-	ctx := context.Background()
-	mockAuth := new(MockAuthService)
-
-	session := &Session{UserID: "viewer-1", Email: "viewer@example.com"}
-	mockAuth.On("ValidateSession", ctx, "viewer-token").Return(session, nil)
-	mockAuth.On("HasPermissionAPI", ctx, "viewer-1", "view", "api-keys").Return(false, nil)
-
-	handler := &Handler{auth: mockAuth}
-
-	req := &events.LambdaFunctionURLRequest{
-		Headers: map[string]string{"Authorization": "Bearer viewer-token"},
-	}
-
-	_, err := handler.listAPIKeysUsageStats(ctx, req)
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), "permission denied")
-	mockAuth.AssertNotCalled(t, "GetAPIKeysUsageStatsAPI", mock.Anything, mock.Anything)
-}
+// listAPIKeysUsageStats handler tests moved to handler_apikeys_usage_test.go
+// alongside the handler (CodeRabbit finding on PR #1523 -- keep the usage-
+// stats bounded context in its own file pair).
 
 func TestFormatTimePtr(t *testing.T) {
 	t.Run("nil pointer returns empty string", func(t *testing.T) {
diff --git a/internal/api/handler_apikeys_usage.go b/internal/api/handler_apikeys_usage.go
new file mode 100644
index 000000000..126879c86
--- /dev/null
+++ b/internal/api/handler_apikeys_usage.go
@@ -0,0 +1,42 @@
+package api
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/aws/aws-lambda-go/events"
+)
+
+// API Key usage-stats handler.
+//
+// Split out of handler_apikeys.go / router.go (CodeRabbit finding on PR
+// #1523) so the new per-API-key usage-stats surface has its own bounded-
+// context file rather than growing the already-oversized router.go and
+// handler_apikeys.go further.
+
+// listAPIKeysUsageStats handles GET /api/api-keys/usage-stats.
+//
+// Returns a section-level summary scoped to the calling user's own keys:
+// total active, total requests (fixed-window count + lifetime), and the
+// top-3 keys by window activity. Scope is identical to listAPIKeys -- both
+// gate on the same view/api-keys permission so the section header and the
+// row list can never disagree about visibility.
+func (h *Handler) listAPIKeysUsageStats(ctx context.Context, req *events.LambdaFunctionURLRequest) (any, error) {
+	session, err := h.requirePermission(ctx, req, "view", "api-keys")
+	if err != nil {
+		return nil, err
+	}
+
+	stats, err := h.auth.GetAPIKeysUsageStatsAPI(ctx, session.UserID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load API key usage stats: %w", err)
+	}
+
+	return stats, nil
+}
+
+// listAPIKeysUsageStatsHandler is the router-level wrapper for
+// listAPIKeysUsageStats, registered against GET /api/api-keys/usage-stats.
+func (r *Router) listAPIKeysUsageStatsHandler(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error) {
+	return r.h.listAPIKeysUsageStats(ctx, req)
+}
diff --git a/internal/api/handler_apikeys_usage_test.go b/internal/api/handler_apikeys_usage_test.go
new file mode 100644
index 000000000..e5d1da507
--- /dev/null
+++ b/internal/api/handler_apikeys_usage_test.go
@@ -0,0 +1,99 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/aws/aws-lambda-go/events"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+// listAPIKeysUsageStats handler -- section-level summary (issue #340/#344
+// deferred sub-task). Mirrors the listAPIKeys test layout: happy path for
+// an authenticated session, a no-auth-service failure, a service-error
+// passthrough, and a permission-denied path for a caller lacking the
+// view/api-keys permission.
+
+func TestHandler_listAPIKeysUsageStats_Success(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+
+	session := &Session{UserID: "user-123", Email: "user@example.com"}
+	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
+	mockAuth.grantAdmin()
+
+	expectedStats := map[string]any{
+		"total_active":            2,
+		"total_requests_window":   int64(15),
+		"total_requests_lifetime": int64(120),
+		"top_keys":                []map[string]any{{"id": "key-1", "name": "k1", "key_prefix": "abc12345", "request_count_window": int64(10)}},
+	}
+	mockAuth.On("GetAPIKeysUsageStatsAPI", ctx, "user-123").Return(expectedStats, nil)
+
+	handler := &Handler{auth: mockAuth}
+
+	req := &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"Authorization": "Bearer test-token"},
+	}
+
+	result, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.NoError(t, err)
+	got, ok := result.(map[string]any)
+	require.True(t, ok)
+	assert.Equal(t, 2, got["total_active"])
+	mockAuth.AssertCalled(t, "GetAPIKeysUsageStatsAPI", ctx, "user-123")
+}
+
+func TestHandler_listAPIKeysUsageStats_NoAuthService(t *testing.T) {
+	ctx := context.Background()
+	handler := &Handler{}
+
+	req := &events.LambdaFunctionURLRequest{}
+
+	_, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "authentication service not configured")
+}
+
+func TestHandler_listAPIKeysUsageStats_ServiceError(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+
+	session := &Session{UserID: "user-123", Email: "user@example.com"}
+	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
+	mockAuth.grantAdmin()
+	mockAuth.On("GetAPIKeysUsageStatsAPI", ctx, "user-123").Return(nil, errors.New("database error"))
+
+	handler := &Handler{auth: mockAuth}
+
+	req := &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"Authorization": "Bearer test-token"},
+	}
+
+	_, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to load API key usage stats")
+}
+
+func TestHandler_listAPIKeysUsageStats_PermissionDenied(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+
+	session := &Session{UserID: "viewer-1", Email: "viewer@example.com"}
+	mockAuth.On("ValidateSession", ctx, "viewer-token").Return(session, nil)
+	mockAuth.On("HasPermissionAPI", ctx, "viewer-1", "view", "api-keys").Return(false, nil)
+
+	handler := &Handler{auth: mockAuth}
+
+	req := &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"Authorization": "Bearer viewer-token"},
+	}
+
+	_, err := handler.listAPIKeysUsageStats(ctx, req)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "permission denied")
+	mockAuth.AssertNotCalled(t, "GetAPIKeysUsageStatsAPI", mock.Anything, mock.Anything)
+}
diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index aa2f9c401..25afe7251 100644
--- a/internal/api/openapi.yaml
+++ b/internal/api/openapi.yaml
@@ -2284,13 +2284,25 @@ components:
           type: integer
           format: int64
           description: Lifetime request count since the key was created.
-        request_count_24h:
+        request_count_window:
           type: integer
           format: int64
           description: |
-            Rolling 24h request count. Resets when the previous window
-            crosses 24h since its first request -- the value is "requests
-            in the last 24h", not "requests today".
+            Request count since request_count_window_start. This is a
+            FIXED/TUMBLING window, not a true trailing-24h rolling count:
+            once the window is older than 24h, the next request resets
+            both this count (to 1) and request_count_window_start (to
+            now), discarding whatever count the previous window had even
+            if some of those requests happened within the preceding 24h.
+            Use request_count_window_start to see exactly which period
+            this count covers.
+        request_count_window_start:
+          type: string
+          format: date-time
+          nullable: true
+          description: |
+            Timestamp the current request_count_window began at. Null
+            when the key has never recorded a request.
 
     APIKeysUsageStats:
       type: object
@@ -2298,10 +2310,13 @@ components:
         total_active:
           type: integer
           description: Number of currently-active API keys for the caller.
-        total_requests_24h:
+        total_requests_window:
           type: integer
           format: int64
-          description: Sum of request_count_24h across the caller's keys.
+          description: |
+            Sum of request_count_window across the caller's keys. Each
+            summand is a fixed-window count (see APIKeyInfo.request_count_window),
+            not a true rolling 24h total.
         total_requests_lifetime:
           type: integer
           format: int64
@@ -2309,8 +2324,9 @@ components:
         top_keys:
           type: array
           description: |
-            Top keys by 24h request count (lifetime count as tiebreaker).
-            At most 3 entries; keys with zero 24h activity are omitted.
+            Top keys by request_count_window (lifetime count as
+            tiebreaker). At most 3 entries; keys with zero window
+            activity are omitted.
           items:
             type: object
             properties:
@@ -2320,7 +2336,7 @@ components:
                 type: string
               key_prefix:
                 type: string
-              request_count_24h:
+              request_count_window:
                 type: integer
                 format: int64
 
diff --git a/internal/api/router.go b/internal/api/router.go
index 3388c9c66..03bc2552e 100644
--- a/internal/api/router.go
+++ b/internal/api/router.go
@@ -739,9 +739,9 @@ func (r *Router) listAPIKeysHandler(ctx context.Context, req *events.LambdaFunct
 	return r.h.listAPIKeys(ctx, req)
 }
 
-func (r *Router) listAPIKeysUsageStatsHandler(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error) {
-	return r.h.listAPIKeysUsageStats(ctx, req)
-}
+// listAPIKeysUsageStatsHandler lives in handler_apikeys_usage.go alongside
+// its handler so the usage-stats feature stays in its own bounded-context
+// file instead of growing this already-oversized router further.
 
 func (r *Router) createAPIKeyHandler(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error) {
 	return r.h.createAPIKey(ctx, req)
diff --git a/internal/api/types.go b/internal/api/types.go
index 237b0b9b7..4bc985e5f 100644
--- a/internal/api/types.go
+++ b/internal/api/types.go
@@ -209,8 +209,8 @@ type AuthServiceInterface interface {
 	CreateAPIKeyAPI(ctx context.Context, userID string, req any) (any, error)
 	ListUserAPIKeysAPI(ctx context.Context, userID string) (any, error)
 	// GetAPIKeysUsageStatsAPI returns the section-level usage summary
-	// (active count, 24h/lifetime request totals, top-3 most active
-	// keys) for the calling user's own API keys.
+	// (active count, fixed-window/lifetime request totals, top-3 most
+	// active keys) for the calling user's own API keys.
 	GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error)
 	DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error
 	RevokeAPIKeyAPI(ctx context.Context, userID, keyID string) error
diff --git a/internal/auth/interfaces.go b/internal/auth/interfaces.go
index f58db2758..24e9032e5 100644
--- a/internal/auth/interfaces.go
+++ b/internal/auth/interfaces.go
@@ -50,9 +50,10 @@ type StoreInterface interface {
 	UpdateAPIKey(ctx context.Context, key *UserAPIKey) error
 	UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error
 	// RecordAPIKeyUsage atomically updates last_used_at and increments
-	// request_count_total + request_count_24h. The 24h counter resets
-	// (along with its window-start) when the existing window is older
-	// than 24h. See migration 000094 for the column shape.
+	// request_count_total + request_count_window. request_count_window is a
+	// fixed/tumbling window count (not a true trailing-24h rolling count):
+	// it resets (along with request_count_window_start) when the existing
+	// window is older than 24h. See migration 000093 for the column shape.
 	RecordAPIKeyUsage(ctx context.Context, keyID string) error
 	DeleteAPIKey(ctx context.Context, keyID string) error
 
diff --git a/internal/auth/service_apikeys.go b/internal/auth/service_apikeys.go
index b7f55655e..1e6f66fee 100644
--- a/internal/auth/service_apikeys.go
+++ b/internal/auth/service_apikeys.go
@@ -289,7 +289,7 @@ func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserA
 	// concurrent requests for the same key are deduplicated rather than
 	// spawning an unbounded number of goroutines (DoS amplifier on a
 	// revoked key). The store does an atomic single-row UPDATE -- see
-	// PostgresStore.RecordAPIKeyUsage for the rolling-24h-window logic.
+	// PostgresStore.RecordAPIKeyUsage for the fixed-window-reset logic.
 	keyID := key.ID
 	go func() {
 		if _, sfErr, _ := s.lastUsedSFG.Do(keyID, func() (any, error) {
@@ -319,9 +319,10 @@ func (s *Service) UpdateLastUsed(ctx context.Context, keyID string) error {
 	return s.store.UpdateAPIKeyLastUsed(ctx, keyID)
 }
 
-// RecordUsage updates last_used_at and increments both the lifetime and
-// rolling-24h request counters for the key. See
-// PostgresStore.RecordAPIKeyUsage for the atomic SQL.
+// RecordUsage updates last_used_at and increments both the lifetime counter
+// and the fixed-window request counter for the key. See
+// PostgresStore.RecordAPIKeyUsage for the atomic SQL and the window's
+// tumbling-reset semantics.
 func (s *Service) RecordUsage(ctx context.Context, keyID string) error {
 	return s.store.RecordAPIKeyUsage(ctx, keyID)
 }
diff --git a/internal/auth/service_apikeys_api.go b/internal/auth/service_apikeys_api.go
index a9358b61b..ebcc424da 100644
--- a/internal/auth/service_apikeys_api.go
+++ b/internal/auth/service_apikeys_api.go
@@ -13,13 +13,13 @@ import (
 // numbers) -- kept small since the summary card is a glance-level widget.
 const apiKeyUsageTopKeysLimit = 3
 
-// sortAPIKeysByActivity sorts in place by request_count_24h desc, with
+// sortAPIKeysByActivity sorts in place by request_count_window desc, with
 // request_count_total desc as the tiebreaker. Extracted as a helper so
 // it can be unit-tested without going through the full service.
 func sortAPIKeysByActivity(keys []*UserAPIKey) {
 	sort.SliceStable(keys, func(i, j int) bool {
-		if keys[i].RequestCount24h != keys[j].RequestCount24h {
-			return keys[i].RequestCount24h > keys[j].RequestCount24h
+		if keys[i].RequestCountWindow != keys[j].RequestCountWindow {
+			return keys[i].RequestCountWindow > keys[j].RequestCountWindow
 		}
 		return keys[i].RequestCountTotal > keys[j].RequestCountTotal
 	})
@@ -37,35 +37,45 @@ type APICreateAPIKeyRequest struct {
 
 // APIKeyInfo represents public API key information (without sensitive data).
 type APIKeyInfo struct {
-	CreatedAt   time.Time    `json:"created_at"`
-	ExpiresAt   *time.Time   `json:"expires_at,omitempty"`
-	LastUsedAt  *time.Time   `json:"last_used_at,omitempty"`
-	ID          string       `json:"id"`
-	Name        string       `json:"name"`
-	KeyPrefix   string       `json:"key_prefix"`
-	Permissions []Permission `json:"permissions,omitempty"`
-	IsActive    bool         `json:"is_active"`
-	// Usage counters (issue #340/#344 deferred sub-task).
-	RequestCountTotal int64 `json:"request_count_total"`
-	RequestCount24h   int64 `json:"request_count_24h"`
+	CreatedAt  time.Time  `json:"created_at"`
+	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
+	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
+	// RequestCountWindowStart is when the current request_count_window
+	// began; nil means the key has never recorded a request. Exposed so
+	// consumers know exactly which period RequestCountWindow covers
+	// instead of assuming a true trailing "last 24h".
+	RequestCountWindowStart *time.Time   `json:"request_count_window_start,omitempty"`
+	ID                      string       `json:"id"`
+	Name                    string       `json:"name"`
+	KeyPrefix               string       `json:"key_prefix"`
+	Permissions             []Permission `json:"permissions,omitempty"`
+	IsActive                bool         `json:"is_active"`
+	// Usage counters (issue #340/#344 deferred sub-task). RequestCountWindow
+	// is a fixed/tumbling window count, not a true rolling 24h total -- see
+	// PostgresStore.RecordAPIKeyUsage and RequestCountWindowStart above.
+	RequestCountTotal  int64 `json:"request_count_total"`
+	RequestCountWindow int64 `json:"request_count_window"`
 }
 
 // APIKeysUsageStatsTopKey is one entry in the top-keys list returned by
-// GetAPIKeysUsageStatsAPI. Trimmed to identifier + 24h count so the UI
+// GetAPIKeysUsageStatsAPI. Trimmed to identifier + window count so the UI
 // doesn't have to re-derive anything from the full APIKeyInfo blob.
 type APIKeysUsageStatsTopKey struct {
-	ID              string `json:"id"`
-	Name            string `json:"name"`
-	KeyPrefix       string `json:"key_prefix"`
-	RequestCount24h int64  `json:"request_count_24h"`
+	ID                 string `json:"id"`
+	Name               string `json:"name"`
+	KeyPrefix          string `json:"key_prefix"`
+	RequestCountWindow int64  `json:"request_count_window"`
 }
 
 // APIKeysUsageStatsResponse is the summary payload for the API keys
 // section header (issue #340/#344 deferred sub-task). Scoped to the
 // calling user's own keys -- same scope as ListUserAPIKeysAPI.
+//
+// TotalRequestsWindow sums each key's fixed-window counter (see
+// PostgresStore.RecordAPIKeyUsage); it is NOT a true trailing-24h total.
 type APIKeysUsageStatsResponse struct {
 	TotalActive           int                       `json:"total_active"`
-	TotalRequests24h      int64                     `json:"total_requests_24h"`
+	TotalRequestsWindow   int64                     `json:"total_requests_window"`
 	TotalRequestsLifetime int64                     `json:"total_requests_lifetime"`
 	TopKeys               []APIKeysUsageStatsTopKey `json:"top_keys"`
 }
@@ -120,16 +130,17 @@ func (s *Service) CreateAPIKeyAPI(ctx context.Context, userID string, req any) (
 		APIKey: apiKey,
 		KeyID:  keyInfo.ID,
 		Info: &APIKeyInfo{
-			ID:                keyInfo.ID,
-			Name:              keyInfo.Name,
-			KeyPrefix:         keyInfo.KeyPrefix,
-			Permissions:       keyInfo.Permissions,
-			ExpiresAt:         keyInfo.ExpiresAt,
-			CreatedAt:         keyInfo.CreatedAt,
-			LastUsedAt:        keyInfo.LastUsedAt,
-			IsActive:          keyInfo.IsActive,
-			RequestCountTotal: keyInfo.RequestCountTotal,
-			RequestCount24h:   keyInfo.RequestCount24h,
+			ID:                      keyInfo.ID,
+			Name:                    keyInfo.Name,
+			KeyPrefix:               keyInfo.KeyPrefix,
+			Permissions:             keyInfo.Permissions,
+			ExpiresAt:               keyInfo.ExpiresAt,
+			CreatedAt:               keyInfo.CreatedAt,
+			LastUsedAt:              keyInfo.LastUsedAt,
+			IsActive:                keyInfo.IsActive,
+			RequestCountTotal:       keyInfo.RequestCountTotal,
+			RequestCountWindow:      keyInfo.RequestCountWindow,
+			RequestCountWindowStart: keyInfo.RequestCountWindowStart,
 		},
 	}, nil
 }
@@ -145,16 +156,17 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 	apiKeys := make([]*APIKeyInfo, 0, len(keys))
 	for _, key := range keys {
 		apiKeys = append(apiKeys, &APIKeyInfo{
-			ID:                key.ID,
-			Name:              key.Name,
-			KeyPrefix:         key.KeyPrefix,
-			Permissions:       key.Permissions,
-			ExpiresAt:         key.ExpiresAt,
-			CreatedAt:         key.CreatedAt,
-			LastUsedAt:        key.LastUsedAt,
-			IsActive:          key.IsActive,
-			RequestCountTotal: key.RequestCountTotal,
-			RequestCount24h:   key.RequestCount24h,
+			ID:                      key.ID,
+			Name:                    key.Name,
+			KeyPrefix:               key.KeyPrefix,
+			Permissions:             key.Permissions,
+			ExpiresAt:               key.ExpiresAt,
+			CreatedAt:               key.CreatedAt,
+			LastUsedAt:              key.LastUsedAt,
+			IsActive:                key.IsActive,
+			RequestCountTotal:       key.RequestCountTotal,
+			RequestCountWindow:      key.RequestCountWindow,
+			RequestCountWindowStart: key.RequestCountWindowStart,
 		})
 	}
 
@@ -166,12 +178,12 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 // GetAPIKeysUsageStatsAPI computes section-level usage stats for the
 // calling user's own API keys. Aggregated in-process so we don't need a
 // separate DB round-trip -- ListUserAPIKeys already returns the per-key
-// counters from migration 000094.
+// counters from migration 000093.
 //
-// The "top keys" list is sorted by request_count_24h descending, with
+// The "top keys" list is sorted by request_count_window descending, with
 // total-lifetime as the tiebreaker so a long-running idle key doesn't
-// outrank an active one with the same 24h count. Up to
-// apiKeyUsageTopKeysLimit entries are surfaced; keys with zero 24h
+// outrank an active one with the same window count. Up to
+// apiKeyUsageTopKeysLimit entries are surfaced; keys with zero window
 // activity are omitted rather than shown as an uninformative "top key".
 func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error) {
 	keys, err := s.ListUserAPIKeys(ctx, userID)
@@ -186,7 +198,7 @@ func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (a
 		if k.IsActive {
 			resp.TotalActive++
 		}
-		resp.TotalRequests24h += k.RequestCount24h
+		resp.TotalRequestsWindow += k.RequestCountWindow
 		resp.TotalRequestsLifetime += k.RequestCountTotal
 	}
 
@@ -200,14 +212,14 @@ func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (a
 	}
 	for i := 0; i < limit; i++ {
 		k := sorted[i]
-		if k.RequestCount24h == 0 {
+		if k.RequestCountWindow == 0 {
 			break
 		}
 		resp.TopKeys = append(resp.TopKeys, APIKeysUsageStatsTopKey{
-			ID:              k.ID,
-			Name:            k.Name,
-			KeyPrefix:       k.KeyPrefix,
-			RequestCount24h: k.RequestCount24h,
+			ID:                 k.ID,
+			Name:               k.Name,
+			KeyPrefix:          k.KeyPrefix,
+			RequestCountWindow: k.RequestCountWindow,
 		})
 	}
 
diff --git a/internal/auth/service_apikeys_api_test.go b/internal/auth/service_apikeys_api_test.go
index cafd9dfb7..408e78f21 100644
--- a/internal/auth/service_apikeys_api_test.go
+++ b/internal/auth/service_apikeys_api_test.go
@@ -468,11 +468,11 @@ func TestService_ValidateUserAPIKeyAPI(t *testing.T) {
 }
 
 func TestSortAPIKeysByActivity(t *testing.T) {
-	t.Run("sorts by 24h count descending", func(t *testing.T) {
+	t.Run("sorts by window count descending", func(t *testing.T) {
 		keys := []*UserAPIKey{
-			{ID: "low", RequestCount24h: 1, RequestCountTotal: 100},
-			{ID: "high", RequestCount24h: 10, RequestCountTotal: 5},
-			{ID: "mid", RequestCount24h: 5, RequestCountTotal: 50},
+			{ID: "low", RequestCountWindow: 1, RequestCountTotal: 100},
+			{ID: "high", RequestCountWindow: 10, RequestCountTotal: 5},
+			{ID: "mid", RequestCountWindow: 5, RequestCountTotal: 50},
 		}
 
 		sortAPIKeysByActivity(keys)
@@ -485,8 +485,8 @@ func TestSortAPIKeysByActivity(t *testing.T) {
 
 	t.Run("uses lifetime total as tiebreaker", func(t *testing.T) {
 		keys := []*UserAPIKey{
-			{ID: "idle-high-lifetime", RequestCount24h: 3, RequestCountTotal: 900},
-			{ID: "active-low-lifetime", RequestCount24h: 3, RequestCountTotal: 10},
+			{ID: "idle-high-lifetime", RequestCountWindow: 3, RequestCountTotal: 900},
+			{ID: "active-low-lifetime", RequestCountWindow: 3, RequestCountTotal: 10},
 		}
 
 		sortAPIKeysByActivity(keys)
@@ -500,17 +500,17 @@ func TestSortAPIKeysByActivity(t *testing.T) {
 func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 	ctx := context.Background()
 
-	t.Run("aggregates totals and returns top-3 by 24h activity", func(t *testing.T) {
+	t.Run("aggregates totals and returns top-3 by window activity", func(t *testing.T) {
 		mockStore := new(MockStore)
 		t.Cleanup(func() { mockStore.AssertExpectations(t) })
 		service := &Service{store: mockStore}
 
 		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
 		keys := []*UserAPIKey{
-			{ID: "key-1", Name: "Busy", KeyPrefix: "aaaa1111", IsActive: true, RequestCount24h: 30, RequestCountTotal: 300},
-			{ID: "key-2", Name: "Medium", KeyPrefix: "bbbb2222", IsActive: true, RequestCount24h: 12, RequestCountTotal: 120},
-			{ID: "key-3", Name: "Quiet", KeyPrefix: "cccc3333", IsActive: false, RequestCount24h: 3, RequestCountTotal: 60},
-			{ID: "key-4", Name: "Idle", KeyPrefix: "dddd4444", IsActive: true, RequestCount24h: 0, RequestCountTotal: 5},
+			{ID: "key-1", Name: "Busy", KeyPrefix: "aaaa1111", IsActive: true, RequestCountWindow: 30, RequestCountTotal: 300},
+			{ID: "key-2", Name: "Medium", KeyPrefix: "bbbb2222", IsActive: true, RequestCountWindow: 12, RequestCountTotal: 120},
+			{ID: "key-3", Name: "Quiet", KeyPrefix: "cccc3333", IsActive: false, RequestCountWindow: 3, RequestCountTotal: 60},
+			{ID: "key-4", Name: "Idle", KeyPrefix: "dddd4444", IsActive: true, RequestCountWindow: 0, RequestCountTotal: 5},
 		}
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
 		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
@@ -521,27 +521,27 @@ func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 		resp, ok := result.(*APIKeysUsageStatsResponse)
 		require.True(t, ok)
 		assert.Equal(t, 3, resp.TotalActive) // key-3 is inactive
-		assert.Equal(t, int64(45), resp.TotalRequests24h)
+		assert.Equal(t, int64(45), resp.TotalRequestsWindow)
 		assert.Equal(t, int64(485), resp.TotalRequestsLifetime)
 		require.Len(t, resp.TopKeys, 3)
 		assert.Equal(t, "key-1", resp.TopKeys[0].ID)
 		assert.Equal(t, "key-2", resp.TopKeys[1].ID)
 		assert.Equal(t, "key-3", resp.TopKeys[2].ID)
-		// key-4 has zero 24h activity and must be omitted, even though the
+		// key-4 has zero window activity and must be omitted, even though the
 		// top-N slice has room for a 4th entry.
 		for _, k := range resp.TopKeys {
 			assert.NotEqual(t, "key-4", k.ID)
 		}
 	})
 
-	t.Run("omits top list entirely when no key has 24h activity", func(t *testing.T) {
+	t.Run("omits top list entirely when no key has window activity", func(t *testing.T) {
 		mockStore := new(MockStore)
 		t.Cleanup(func() { mockStore.AssertExpectations(t) })
 		service := &Service{store: mockStore}
 
 		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
 		keys := []*UserAPIKey{
-			{ID: "key-1", IsActive: true, RequestCount24h: 0, RequestCountTotal: 7},
+			{ID: "key-1", IsActive: true, RequestCountWindow: 0, RequestCountTotal: 7},
 		}
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
 		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
@@ -552,7 +552,7 @@ func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 		resp, ok := result.(*APIKeysUsageStatsResponse)
 		require.True(t, ok)
 		assert.Equal(t, 1, resp.TotalActive)
-		assert.Equal(t, int64(0), resp.TotalRequests24h)
+		assert.Equal(t, int64(0), resp.TotalRequestsWindow)
 		assert.Equal(t, int64(7), resp.TotalRequestsLifetime)
 		assert.Empty(t, resp.TopKeys)
 	})
@@ -572,7 +572,7 @@ func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 		resp, ok := result.(*APIKeysUsageStatsResponse)
 		require.True(t, ok)
 		assert.Equal(t, 0, resp.TotalActive)
-		assert.Equal(t, int64(0), resp.TotalRequests24h)
+		assert.Equal(t, int64(0), resp.TotalRequestsWindow)
 		assert.Equal(t, int64(0), resp.TotalRequestsLifetime)
 		assert.Empty(t, resp.TopKeys)
 	})
diff --git a/internal/auth/store_postgres.go b/internal/auth/store_postgres.go
index 4fda0f419..2779d8eec 100644
--- a/internal/auth/store_postgres.go
+++ b/internal/auth/store_postgres.go
@@ -781,7 +781,7 @@ func (s *PostgresStore) GetAPIKeyByID(ctx context.Context, keyID string) (*UserA
 	query := `
 		SELECT id, user_id, name, key_prefix, key_hash, permissions,
 		       is_active, expires_at, created_at, last_used_at,
-		       request_count_total, request_count_24h
+		       request_count_total, request_count_window, request_count_window_start
 		FROM api_keys
 		WHERE id = $1
 	`
@@ -794,7 +794,7 @@ func (s *PostgresStore) GetAPIKeyByHash(ctx context.Context, keyHash string) (*U
 	query := `
 		SELECT id, user_id, name, key_prefix, key_hash, permissions,
 		       is_active, expires_at, created_at, last_used_at,
-		       request_count_total, request_count_24h
+		       request_count_total, request_count_window, request_count_window_start
 		FROM api_keys
 		WHERE key_hash = $1 AND is_active = true
 		  AND (expires_at IS NULL OR expires_at > NOW())
@@ -808,7 +808,7 @@ func (s *PostgresStore) ListAPIKeysByUser(ctx context.Context, userID string) ([
 	query := `
 		SELECT id, user_id, name, key_prefix, key_hash, permissions,
 		       is_active, expires_at, created_at, last_used_at,
-		       request_count_total, request_count_24h
+		       request_count_total, request_count_window, request_count_window_start
 		FROM api_keys
 		WHERE user_id = $1
 		ORDER BY created_at DESC
@@ -876,7 +876,7 @@ func (s *PostgresStore) UpdateAPIKey(ctx context.Context, key *UserAPIKey) error
 // UpdateAPIKeyLastUsed atomically updates the last_used_at timestamp for an
 // API key. Retained for backwards compatibility with callers that only need
 // the timestamp update -- production code routes through RecordAPIKeyUsage,
-// which additionally maintains the usage counters from migration 000094.
+// which additionally maintains the usage counters from migration 000093.
 func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error {
 	query := `UPDATE api_keys SET last_used_at = NOW() WHERE id = $1`
 	result, err := s.db.Exec(ctx, query, keyID)
@@ -890,14 +890,24 @@ func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string)
 }
 
 // RecordAPIKeyUsage atomically updates last_used_at, increments
-// request_count_total, and increments-or-resets request_count_24h based on
-// whether the rolling 24h window is still current.
+// request_count_total, and increments-or-resets request_count_window based
+// on whether the current window is still within 24h of its start.
 //
-// The single UPDATE does the window decision inline:
+// request_count_window is a FIXED/TUMBLING window counter, not a true
+// trailing-24h rolling count: the single UPDATE does the window decision
+// inline --
 //   - if window_start IS NULL OR (NOW() - window_start) >= 24h, start a
-//     fresh window (window_start = NOW(), count = 1).
+//     fresh window (window_start = NOW(), count = 1) -- this DISCARDS
+//     whatever count the previous window had, even if some of those
+//     requests happened within the preceding 24h of NOW().
 //   - otherwise increment the existing count.
 //
+// A request made moments before a window resets is therefore dropped from
+// the count as soon as the next request starts a new window; an idle key's
+// stale count also lingers unchanged until its next request. Callers that
+// need the actual period covered should read request_count_window_start
+// rather than assuming "requests in the last 24h".
+//
 // Doing it in one statement keeps the update atomic per row, so two
 // concurrent calls can't both see "stale window" and reset to 1 in
 // parallel -- pgx serializes updates to the same row.
@@ -906,17 +916,17 @@ func (s *PostgresStore) RecordAPIKeyUsage(ctx context.Context, keyID string) err
 		UPDATE api_keys
 		SET last_used_at = NOW(),
 		    request_count_total = request_count_total + 1,
-		    request_count_24h = CASE
-		        WHEN request_count_24h_window_start IS NULL
-		             OR NOW() - request_count_24h_window_start >= INTERVAL '24 hours'
+		    request_count_window = CASE
+		        WHEN request_count_window_start IS NULL
+		             OR NOW() - request_count_window_start >= INTERVAL '24 hours'
 		        THEN 1
-		        ELSE request_count_24h + 1
+		        ELSE request_count_window + 1
 		    END,
-		    request_count_24h_window_start = CASE
-		        WHEN request_count_24h_window_start IS NULL
-		             OR NOW() - request_count_24h_window_start >= INTERVAL '24 hours'
+		    request_count_window_start = CASE
+		        WHEN request_count_window_start IS NULL
+		             OR NOW() - request_count_window_start >= INTERVAL '24 hours'
 		        THEN NOW()
-		        ELSE request_count_24h_window_start
+		        ELSE request_count_window_start
 		    END
 		WHERE id = $1
 	`
@@ -1071,7 +1081,7 @@ func (s *PostgresStore) scanGroup(scanner Scanner) (*Group, error) {
 func (s *PostgresStore) scanAPIKey(scanner Scanner) (*UserAPIKey, error) {
 	var key UserAPIKey
 	var permissionsJSON []byte
-	var expiresAt, lastUsedAt sql.NullTime
+	var expiresAt, lastUsedAt, windowStart sql.NullTime
 
 	err := scanner.Scan(
 		&key.ID,
@@ -1085,7 +1095,8 @@ func (s *PostgresStore) scanAPIKey(scanner Scanner) (*UserAPIKey, error) {
 		&key.CreatedAt,
 		&lastUsedAt,
 		&key.RequestCountTotal,
-		&key.RequestCount24h,
+		&key.RequestCountWindow,
+		&windowStart,
 	)
 
 	if err != nil {
@@ -1109,6 +1120,9 @@ func (s *PostgresStore) scanAPIKey(scanner Scanner) (*UserAPIKey, error) {
 	if lastUsedAt.Valid {
 		key.LastUsedAt = &lastUsedAt.Time
 	}
+	if windowStart.Valid {
+		key.RequestCountWindowStart = &windowStart.Time
+	}
 
 	return &key, nil
 }
diff --git a/internal/auth/store_postgres_pgxmock_test.go b/internal/auth/store_postgres_pgxmock_test.go
index 499d34218..01a447253 100644
--- a/internal/auth/store_postgres_pgxmock_test.go
+++ b/internal/auth/store_postgres_pgxmock_test.go
@@ -423,7 +423,7 @@ func TestPGXMock_ListUsers_RowError(t *testing.T) {
 var apiKeyColumns = []string{
 	"id", "user_id", "name", "key_prefix", "key_hash", "permissions",
 	"is_active", "expires_at", "created_at", "last_used_at",
-	"request_count_total", "request_count_24h",
+	"request_count_total", "request_count_window", "request_count_window_start",
 }
 
 func TestPGXMock_ListAPIKeysByUser_Success(t *testing.T) {
@@ -433,17 +433,18 @@ func TestPGXMock_ListAPIKeysByUser_Success(t *testing.T) {
 	created := time.Date(2026, 3, 4, 5, 6, 7, 0, time.UTC)
 	expires := created.Add(24 * time.Hour)
 	lastUsed := created.Add(time.Hour)
+	windowStart := created.Add(30 * time.Minute)
 
 	rows := pgxmock.NewRows(apiKeyColumns).
 		AddRow(
 			"key-1", "user-1", "ci key", "cudly_ab", "hash-1",
 			[]byte(`[{"action":"view","resource":"recommendations"}]`), true, expires, created, lastUsed,
-			int64(42), int64(3),
+			int64(42), int64(3), windowStart,
 		).
 		AddRow(
 			"key-2", "user-1", "old key", "cudly_cd", "hash-2",
 			[]byte(`[]`), false, nil, created, nil,
-			int64(0), int64(0),
+			int64(0), int64(0), nil,
 		)
 
 	mock.ExpectQuery(`(?s)SELECT id, user_id, name, key_prefix, key_hash, permissions,.*FROM api_keys\s+WHERE user_id = \$1\s+ORDER BY created_at DESC`).
@@ -463,14 +464,17 @@ func TestPGXMock_ListAPIKeysByUser_Success(t *testing.T) {
 	require.NotNil(t, keys[0].LastUsedAt)
 	assert.Equal(t, lastUsed, *keys[0].LastUsedAt)
 	assert.Equal(t, int64(42), keys[0].RequestCountTotal)
-	assert.Equal(t, int64(3), keys[0].RequestCount24h)
+	assert.Equal(t, int64(3), keys[0].RequestCountWindow)
+	require.NotNil(t, keys[0].RequestCountWindowStart)
+	assert.Equal(t, windowStart, *keys[0].RequestCountWindowStart)
 
 	assert.Equal(t, "key-2", keys[1].ID)
 	assert.False(t, keys[1].IsActive)
 	assert.Nil(t, keys[1].ExpiresAt)
 	assert.Nil(t, keys[1].LastUsedAt)
 	assert.Equal(t, int64(0), keys[1].RequestCountTotal)
-	assert.Equal(t, int64(0), keys[1].RequestCount24h)
+	assert.Equal(t, int64(0), keys[1].RequestCountWindow)
+	assert.Nil(t, keys[1].RequestCountWindowStart)
 }
 
 func TestPGXMock_ListAPIKeysByUser_QueryError(t *testing.T) {
diff --git a/internal/auth/types.go b/internal/auth/types.go
index c84e81db3..d098fcd7c 100644
--- a/internal/auth/types.go
+++ b/internal/auth/types.go
@@ -78,12 +78,18 @@ type UserAPIKey struct {
 	KeyHash     string       `json:"-" dynamodbav:"KeyHash"`
 	Permissions []Permission `json:"permissions,omitempty" dynamodbav:"Permissions"`
 	IsActive    bool         `json:"is_active" dynamodbav:"IsActive"`
-	// Usage counters (issue #340/#344 deferred sub-task -- migration 000094).
-	// Both default to 0 for legacy rows. RequestCount24h is reset by the
-	// store's RecordAPIKeyUsage path once its window-start is older than
-	// 24h, so it really is a "last 24h" number, not "last calendar day".
-	RequestCountTotal int64 `json:"request_count_total" dynamodbav:"RequestCountTotal"`
-	RequestCount24h   int64 `json:"request_count_24h" dynamodbav:"RequestCount24h"`
+	// Usage counters (issue #340/#344 deferred sub-task -- migration 000093).
+	// Both default to 0 for legacy rows. RequestCountWindow is a
+	// FIXED/TUMBLING window count, not a true trailing-24h rolling count:
+	// the store's RecordAPIKeyUsage path resets it (and RequestCountWindowStart)
+	// to a fresh window once the existing window is older than 24h, so a
+	// request made just before that reset is dropped from the count as soon
+	// as the next request starts a new window. RequestCountWindowStart is
+	// exposed so API consumers can see exactly which period the count
+	// covers instead of assuming "last 24h".
+	RequestCountTotal       int64      `json:"request_count_total" dynamodbav:"RequestCountTotal"`
+	RequestCountWindow      int64      `json:"request_count_window" dynamodbav:"RequestCountWindow"`
+	RequestCountWindowStart *time.Time `json:"request_count_window_start,omitempty" dynamodbav:"RequestCountWindowStart,omitempty"`
 }
 
 // AuthContext represents the complete authorization context for a user
diff --git a/internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql b/internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql
new file mode 100644
index 000000000..b31a7f567
--- /dev/null
+++ b/internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql
@@ -0,0 +1,5 @@
+-- Roll back API key usage counters (000093).
+ALTER TABLE api_keys
+    DROP COLUMN IF EXISTS request_count_window_start,
+    DROP COLUMN IF EXISTS request_count_window,
+    DROP COLUMN IF EXISTS request_count_total;
diff --git a/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
new file mode 100644
index 000000000..4cd54f080
--- /dev/null
+++ b/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
@@ -0,0 +1,33 @@
+-- API key usage counters (deferred sub-task from #340 / #344).
+--
+-- Surface per-key request volume to the Admin -> API Keys UI without
+-- introducing a separate audit-log table. Two counters live directly on
+-- the api_keys row, updated atomically by the same code path that
+-- already maintains last_used_at:
+--
+--   * request_count_total        -- lifetime count since the key was created.
+--   * request_count_window       -- count since request_count_window_start;
+--                                  reset to 1 (with a fresh window_start)
+--                                  the first time RecordAPIKeyUsage sees
+--                                  the window older than 24h. This is a
+--                                  FIXED/TUMBLING window, not a true
+--                                  trailing-24h rolling count: a request
+--                                  just before the window resets is
+--                                  discarded from the count as soon as the
+--                                  next request starts a new window. See
+--                                  store_postgres.go RecordAPIKeyUsage.
+--   * request_count_window_start -- the timestamp the current window
+--                                  started at; NULL until the first
+--                                  request after this migration runs.
+--                                  Exposed via the API so consumers can
+--                                  see exactly which period the count
+--                                  covers instead of assuming "last 24h".
+--
+-- Counters default to 0 so all existing rows show "0 requests" rather
+-- than "(null)" in the UI. The window-start column is nullable because
+-- a row with zero-ever-usage shouldn't lie about when its window began.
+
+ALTER TABLE api_keys
+    ADD COLUMN IF NOT EXISTS request_count_total BIGINT NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS request_count_window BIGINT NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS request_count_window_start TIMESTAMPTZ;
diff --git a/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
deleted file mode 100644
index d6c284e15..000000000
--- a/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
+++ /dev/null
@@ -1,5 +0,0 @@
--- Roll back API key usage counters (000094).
-ALTER TABLE api_keys
-    DROP COLUMN IF EXISTS request_count_24h_window_start,
-    DROP COLUMN IF EXISTS request_count_24h,
-    DROP COLUMN IF EXISTS request_count_total;
diff --git a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
deleted file mode 100644
index 5e4a45003..000000000
--- a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
+++ /dev/null
@@ -1,25 +0,0 @@
--- API key usage counters (deferred sub-task from #340 / #344).
---
--- Surface per-key request volume to the Admin -> API Keys UI without
--- introducing a separate audit-log table. Two counters live directly on
--- the api_keys row, updated atomically by the same code path that
--- already maintains last_used_at:
---
---   * request_count_total       -- lifetime count since the key was created.
---   * request_count_24h         -- rolling 24-hour count; reset by the
---                                 increment path once the window age
---                                 crosses 24h (see store_postgres.go
---                                 RecordAPIKeyUsage).
---   * request_count_24h_window_start -- the timestamp the current 24h
---                                 window started at; NULL until the
---                                 first request after this migration
---                                 runs.
---
--- Counters default to 0 so all existing rows show "0 requests" rather
--- than "(null)" in the UI. The window-start column is nullable because
--- a row with zero-ever-usage shouldn't lie about when its window began.
-
-ALTER TABLE api_keys
-    ADD COLUMN IF NOT EXISTS request_count_total BIGINT NOT NULL DEFAULT 0,
-    ADD COLUMN IF NOT EXISTS request_count_24h BIGINT NOT NULL DEFAULT 0,
-    ADD COLUMN IF NOT EXISTS request_count_24h_window_start TIMESTAMPTZ;

From 101f8f185c37a1dd6681266952804e32f36487ec Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 19:40:02 +0200
Subject: [PATCH 3/8] fix(auth): correct API-key usage stats staleness, scope
 and counting

Adversarial review follow-up on the per-API-key usage stats added in
this PR. Three confirmed correctness bugs, each with a regression test
that fails without its fix.

1. Expired windows were reported as current activity.
   request_count_window is only rewritten by the key's NEXT request, so
   a key that went idle kept its closed window's count on the row
   indefinitely. The read path summed and ranked that column verbatim,
   so the summary card could report thousands of requests "in the
   window" for keys unused for months, and rank a long-dead key as most
   active. Window counters now go through effectiveWindowUsage, which
   reports zero with no window start once the window has closed.

2. Expired keys were counted as active. TotalActive tested only the
   revocation flag, so a key past its expires_at was summarised as
   active while the keys table directly below it rendered the same key
   as "Expired". It now uses validateAPIKeyStatus, the same predicate
   the authentication path applies.

3. Concurrent requests were silently dropped from the counters.
   singleflight collapses concurrent flushes for one key into a single
   DB write, and the flush incremented by a fixed 1, so every request
   arriving during an in-flight write was lost. The undercount grew
   with request rate, i.e. was worst on exactly the busy keys the stats
   exist to surface. Requests are now accumulated in memory and the
   flush writes the whole delta, with a bounded re-drain so a request
   is never stranded until the key's next use. singleflight still bounds
   the write rate to one in-flight DB write per key.

The 24h window length is now a single Go constant passed into the SQL
via make_interval, so the write path and the read-side expiry check
cannot drift. RecordAPIKeyUsage rejects a non-positive delta rather
than issuing a no-op UPDATE.
---
 frontend/src/api/types.ts                     |  10 +-
 frontend/src/types.ts                         |   3 +-
 internal/api/handler_apikeys_usage_test.go    |   3 +
 internal/api/openapi.yaml                     |  40 +++--
 internal/auth/interfaces.go                   |  12 +-
 internal/auth/service.go                      |  15 +-
 internal/auth/service_apikeys.go              | 166 ++++++++++++++---
 internal/auth/service_apikeys_api.go          | 107 +++++++----
 internal/auth/service_apikeys_api_test.go     | 168 +++++++++++++++---
 internal/auth/service_apikeys_test.go         | 114 +++++++++++-
 internal/auth/service_security_test.go        |   2 +-
 internal/auth/store_postgres.go               |  51 +++---
 internal/auth/store_postgres_pgxmock_test.go  |  41 ++++-
 internal/auth/test_helpers.go                 |   4 +-
 internal/auth/types.go                        |  14 +-
 .../000093_api_keys_usage_counters.up.sql     |   9 +-
 internal/mocks/stores.go                      |   4 +-
 internal/server/health_test.go                |   2 +-
 18 files changed, 620 insertions(+), 145 deletions(-)

diff --git a/frontend/src/api/types.ts b/frontend/src/api/types.ts
index 71844b9f0..bd5b139fe 100644
--- a/frontend/src/api/types.ts
+++ b/frontend/src/api/types.ts
@@ -580,7 +580,10 @@ export interface APIKeyInfo {
   // the columns don't blow up the renderer -- but the backend always
   // sends them as of migration 000093. request_count_window is a
   // FIXED/TUMBLING window count, not a true rolling 24h total --
-  // request_count_window_start says exactly which period it covers.
+  // request_count_window_start says exactly which period it covers, and
+  // both come back as 0 / absent once that window has closed, so a key
+  // that went idle reads as no current activity rather than replaying a
+  // count from an old window.
   request_count_total?: number;
   request_count_window?: number;
   request_count_window_start?: string;
@@ -594,8 +597,11 @@ export interface APIKeysUsageStatsTopKey {
 }
 
 export interface APIKeysUsageStats {
+  // Keys that are neither revoked nor expired, i.e. the ones the API will
+  // actually accept.
   total_active: number;
-  // Sum of each key's fixed-window counter -- not a true rolling 24h total.
+  // Sum of each key's fixed-window counter across still-open windows --
+  // not a true rolling 24h total, and the windows are not aligned.
   total_requests_window: number;
   total_requests_lifetime: number;
   top_keys: APIKeysUsageStatsTopKey[];
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 949469171..69517dc87 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -412,7 +412,8 @@ export interface APIKeyInfo {
   // up the renderer -- the backend always sends them as of migration
   // 000093. request_count_window is a FIXED/TUMBLING window count, not
   // a true rolling 24h total -- request_count_window_start says exactly
-  // which period it covers.
+  // which period it covers, and both come back as 0 / absent once that
+  // window has closed.
   request_count_total?: number;
   request_count_window?: number;
   request_count_window_start?: string;
diff --git a/internal/api/handler_apikeys_usage_test.go b/internal/api/handler_apikeys_usage_test.go
index e5d1da507..ef10d1715 100644
--- a/internal/api/handler_apikeys_usage_test.go
+++ b/internal/api/handler_apikeys_usage_test.go
@@ -20,6 +20,7 @@ import (
 func TestHandler_listAPIKeysUsageStats_Success(t *testing.T) {
 	ctx := context.Background()
 	mockAuth := new(MockAuthService)
+	t.Cleanup(func() { mockAuth.AssertExpectations(t) })
 
 	session := &Session{UserID: "user-123", Email: "user@example.com"}
 	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
@@ -61,6 +62,7 @@ func TestHandler_listAPIKeysUsageStats_NoAuthService(t *testing.T) {
 func TestHandler_listAPIKeysUsageStats_ServiceError(t *testing.T) {
 	ctx := context.Background()
 	mockAuth := new(MockAuthService)
+	t.Cleanup(func() { mockAuth.AssertExpectations(t) })
 
 	session := &Session{UserID: "user-123", Email: "user@example.com"}
 	mockAuth.On("ValidateSession", ctx, "test-token").Return(session, nil)
@@ -81,6 +83,7 @@ func TestHandler_listAPIKeysUsageStats_ServiceError(t *testing.T) {
 func TestHandler_listAPIKeysUsageStats_PermissionDenied(t *testing.T) {
 	ctx := context.Background()
 	mockAuth := new(MockAuthService)
+	t.Cleanup(func() { mockAuth.AssertExpectations(t) })
 
 	session := &Session{UserID: "viewer-1", Email: "viewer@example.com"}
 	mockAuth.On("ValidateSession", ctx, "viewer-token").Return(session, nil)
diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index 25afe7251..ed00e3541 100644
--- a/internal/api/openapi.yaml
+++ b/internal/api/openapi.yaml
@@ -1392,8 +1392,10 @@ paths:
       summary: Section-level usage summary for the caller's API keys
       description: |
         Aggregates per-key counters into a single summary card: number of
-        active keys, total requests (24h + lifetime), and the top-3 keys
-        by 24h request count. Scoped to the calling user's own keys.
+        usable keys, total requests (current window + lifetime), and the
+        top-3 keys by current-window request count. Scoped to the calling
+        user's own keys. Counts from windows that have already closed are
+        reported as zero, not as current activity.
       responses:
         '200':
           description: API keys usage stats
@@ -2290,33 +2292,43 @@ components:
           description: |
             Request count since request_count_window_start. This is a
             FIXED/TUMBLING window, not a true trailing-24h rolling count:
-            once the window is older than 24h, the next request resets
-            both this count (to 1) and request_count_window_start (to
-            now), discarding whatever count the previous window had even
-            if some of those requests happened within the preceding 24h.
-            Use request_count_window_start to see exactly which period
-            this count covers.
+            once the window is older than 24h, the next request restarts
+            both this count and request_count_window_start, discarding
+            whatever count the previous window had even if some of those
+            requests happened within the preceding 24h.
+
+            Reported as 0 once the window is older than 24h, even though
+            the underlying row still holds the closed window's count until
+            the key is used again: a key that went idle has no current
+            activity. Use request_count_window_start to see exactly which
+            period this count covers.
         request_count_window_start:
           type: string
           format: date-time
           nullable: true
           description: |
-            Timestamp the current request_count_window began at. Null
-            when the key has never recorded a request.
+            Timestamp the current request_count_window began at. Null when
+            the key has never recorded a request, and also null once the
+            window has closed, since there is then no current period for
+            the count to refer to.
 
     APIKeysUsageStats:
       type: object
       properties:
         total_active:
           type: integer
-          description: Number of currently-active API keys for the caller.
+          description: |
+            Number of the caller's API keys that are currently usable, i.e.
+            neither revoked nor past their expiry. Matches the keys the
+            authentication path will accept.
         total_requests_window:
           type: integer
           format: int64
           description: |
-            Sum of request_count_window across the caller's keys. Each
-            summand is a fixed-window count (see APIKeyInfo.request_count_window),
-            not a true rolling 24h total.
+            Sum of request_count_window across the caller's keys, counting
+            only windows that are still open. Each summand is a fixed-window
+            count (see APIKeyInfo.request_count_window), not a true rolling
+            24h total, and the windows are not aligned with each other.
         total_requests_lifetime:
           type: integer
           format: int64
diff --git a/internal/auth/interfaces.go b/internal/auth/interfaces.go
index 24e9032e5..5fc88a765 100644
--- a/internal/auth/interfaces.go
+++ b/internal/auth/interfaces.go
@@ -49,12 +49,16 @@ type StoreInterface interface {
 	ListAPIKeysByUser(ctx context.Context, userID string) ([]*UserAPIKey, error)
 	UpdateAPIKey(ctx context.Context, key *UserAPIKey) error
 	UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error
-	// RecordAPIKeyUsage atomically updates last_used_at and increments
-	// request_count_total + request_count_window. request_count_window is a
+	// RecordAPIKeyUsage atomically updates last_used_at and adds delta to
+	// request_count_total + request_count_window. delta is the number of
+	// requests in this flush (greater than 1 when concurrent requests were
+	// coalesced) and must be positive. request_count_window is a
 	// fixed/tumbling window count (not a true trailing-24h rolling count):
 	// it resets (along with request_count_window_start) when the existing
-	// window is older than 24h. See migration 000093 for the column shape.
-	RecordAPIKeyUsage(ctx context.Context, keyID string) error
+	// window is older than apiKeyUsageWindow. Stale windows are zeroed on
+	// read, not on write -- see effectiveWindowUsage. See migration 000093
+	// for the column shape.
+	RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error
 	DeleteAPIKey(ctx context.Context, keyID string) error
 
 	// Health check
diff --git a/internal/auth/service.go b/internal/auth/service.go
index be9a47419..fc1040836 100644
--- a/internal/auth/service.go
+++ b/internal/auth/service.go
@@ -8,6 +8,8 @@ import (
 	"fmt"
 	"net/mail"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/LeanerCloud/CUDly/pkg/logging"
@@ -43,9 +45,16 @@ const (
 
 // Service handles authentication and authorization.
 type Service struct {
-	store              StoreInterface
-	emailSender        EmailSenderInterface
-	lastUsedSFG        singleflight.Group
+	store       StoreInterface
+	emailSender EmailSenderInterface
+	lastUsedSFG singleflight.Group
+	// pendingUsage accumulates per-API-key request counts that have not yet
+	// been flushed to the store, keyed by API key ID. pendingUsageMu guards
+	// the map itself; the counters are incremented and drained atomically
+	// without it. See Service.recordUsageAsync for why the count is buffered
+	// instead of incremented once per flush.
+	pendingUsage       map[string]*atomic.Int64
+	pendingUsageMu     sync.Mutex
 	onPasswordChange   func(ctx context.Context, userID, newPassword string)
 	dashboardURL       string
 	csrfKey            []byte
diff --git a/internal/auth/service_apikeys.go b/internal/auth/service_apikeys.go
index 1e6f66fee..54a3d24ca 100644
--- a/internal/auth/service_apikeys.go
+++ b/internal/auth/service_apikeys.go
@@ -8,6 +8,7 @@ import (
 	"encoding/base64"
 	"errors"
 	"fmt"
+	"sync/atomic"
 	"time"
 
 	"github.com/LeanerCloud/CUDly/pkg/logging"
@@ -15,6 +16,27 @@ import (
 	"github.com/jackc/pgx/v5"
 )
 
+const (
+	// apiKeyUsageWindow is the length of the request_count_window bucket
+	// maintained by PostgresStore.RecordAPIKeyUsage. It is the single source
+	// of truth for the window length: the store passes it into the SQL as an
+	// interval and the API read path uses it to decide whether a stored
+	// window has expired (effectiveWindowUsage), so the write and read sides
+	// cannot drift apart.
+	apiKeyUsageWindow = 24 * time.Hour
+
+	// apiKeyUsageFlushTimeout bounds a single usage-counter write. The write
+	// happens off the auth hot path, so a slow database delays the counter,
+	// never the caller's request.
+	apiKeyUsageFlushTimeout = 5 * time.Second
+
+	// maxAPIKeyUsageFlushRounds bounds how many times one flush goroutine
+	// re-drains a key before handing off. Without it, a key under sustained
+	// load would keep a single goroutine writing forever; with it, the
+	// leftover count is simply picked up by the next request's flush.
+	maxAPIKeyUsageFlushRounds = 16
+)
+
 // CreateAPIKey creates a new user API key with scoped permissions
 // Returns the full API key (shown only once), key info, and error.
 func (s *Service) CreateAPIKey(ctx context.Context, userID, name string, permissions []Permission, expiresAt *time.Time) (string, *UserAPIKey, error) {
@@ -283,33 +305,123 @@ func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserA
 		return nil, nil, err
 	}
 
-	// Record usage (last_used_at + counters) asynchronously to avoid
-	// blocking the authentication hot path. singleflight.Group ensures at
-	// most one in-flight DB write per keyID at any moment: subsequent
-	// concurrent requests for the same key are deduplicated rather than
-	// spawning an unbounded number of goroutines (DoS amplifier on a
-	// revoked key). The store does an atomic single-row UPDATE -- see
-	// PostgresStore.RecordAPIKeyUsage for the fixed-window-reset logic.
-	keyID := key.ID
+	s.recordUsageAsync(key.ID)
+
+	return key, user, nil
+}
+
+// recordUsageAsync books one request against keyID and flushes the pending
+// count to the store off the authentication hot path.
+//
+// The count is accumulated in memory first and the flush writes the whole
+// accumulated delta, because singleflight.Group collapses concurrent flushes
+// for the same key into one DB write. Incrementing by a fixed 1 inside the
+// flush would therefore drop every request that arrived while a write was in
+// flight -- a systematic undercount that grows with the key's request rate,
+// i.e. worst exactly on the busy keys the usage stats exist to surface.
+//
+// singleflight is still what bounds the write rate: at most one in-flight DB
+// write per keyID at any moment, so a flood of requests on one key cannot
+// amplify into a flood of database writes.
+func (s *Service) recordUsageAsync(keyID string) {
+	// Book the request BEFORE starting the flush goroutine, so it can never
+	// be missed by a flush that is already draining the counter.
+	s.addPendingUsage(keyID)
+
 	go func() {
-		if _, sfErr, _ := s.lastUsedSFG.Do(keyID, func() (any, error) {
-			defer func() {
-				if r := recover(); r != nil {
-					logging.Warnf("service_apikeys: RecordUsage goroutine panic: %v", r)
-				}
-			}()
-			updateCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-			defer cancel()
-			if err := s.RecordUsage(updateCtx, keyID); err != nil {
-				logging.Debugf("Failed to record API key usage for key %s: %v", keyID, err)
+		defer func() {
+			if r := recover(); r != nil {
+				logging.Warnf("service_apikeys: RecordUsage goroutine panic: %v", r)
+			}
+		}()
+
+		// singleflight hands a late joiner the in-flight flush's result, and
+		// that flush may have drained the counter before this request was
+		// booked. Re-check once the shared flush returns and go round again
+		// while work remains, so a request is never stranded until the key
+		// happens to be used again. Bounded so a key under sustained load
+		// hands off instead of pinning one goroutine to the database.
+		for range maxAPIKeyUsageFlushRounds {
+			if _, sfErr, _ := s.lastUsedSFG.Do(keyID, func() (any, error) {
+				s.flushPendingUsage(keyID)
+				return nil, nil
+			}); sfErr != nil {
+				logging.Debugf("service_apikeys: lastUsedSFG returned error for key %s: %v", keyID, sfErr)
+				return
+			}
+			if s.peekPendingUsage(keyID) == 0 {
+				return
 			}
-			return nil, nil
-		}); sfErr != nil {
-			logging.Debugf("service_apikeys: lastUsedSFG returned error for key %s: %v", keyID, sfErr)
 		}
 	}()
+}
 
-	return key, user, nil
+// addPendingUsage books one not-yet-flushed request against keyID.
+//
+// Entries are never removed: an entry is one atomic int64 and the number of
+// distinct keys is bounded by the number of API keys that exist, so this is
+// a fixed small cost rather than unbounded growth. Removing entries would
+// race with in-flight increments and risk losing counts.
+func (s *Service) addPendingUsage(keyID string) {
+	s.pendingUsageMu.Lock()
+	if s.pendingUsage == nil {
+		s.pendingUsage = make(map[string]*atomic.Int64)
+	}
+	counter, ok := s.pendingUsage[keyID]
+	if !ok {
+		counter = new(atomic.Int64)
+		s.pendingUsage[keyID] = counter
+	}
+	s.pendingUsageMu.Unlock()
+
+	counter.Add(1)
+}
+
+// pendingCounter returns the counter for keyID, or nil if the key has never
+// booked a request. The mutex covers only the map lookup; reads and writes
+// of the returned counter are atomic.
+func (s *Service) pendingCounter(keyID string) *atomic.Int64 {
+	s.pendingUsageMu.Lock()
+	defer s.pendingUsageMu.Unlock()
+	return s.pendingUsage[keyID]
+}
+
+// flushPendingUsage writes the count accumulated for keyID so far to the
+// store. A no-op when nothing is pending.
+//
+// On a store error the drained count is lost rather than retried: the caller
+// is a fire-and-forget goroutine on the auth path, and retrying a usage
+// counter is not worth holding a database connection during an outage. The
+// loss is logged and bounded to the requests in that one flush.
+func (s *Service) flushPendingUsage(keyID string) {
+	delta := s.drainPendingUsage(keyID)
+	if delta == 0 {
+		return
+	}
+	updateCtx, cancel := context.WithTimeout(context.Background(), apiKeyUsageFlushTimeout)
+	defer cancel()
+	if err := s.RecordUsage(updateCtx, keyID, delta); err != nil {
+		logging.Debugf("Failed to record %d API key usage(s) for key %s: %v", delta, keyID, err)
+	}
+}
+
+// drainPendingUsage atomically takes the pending count for keyID, resetting
+// it to zero. Returns 0 when nothing is pending.
+func (s *Service) drainPendingUsage(keyID string) int64 {
+	counter := s.pendingCounter(keyID)
+	if counter == nil {
+		return 0
+	}
+	return counter.Swap(0)
+}
+
+// peekPendingUsage reports the pending count for keyID without consuming it.
+func (s *Service) peekPendingUsage(keyID string) int64 {
+	counter := s.pendingCounter(keyID)
+	if counter == nil {
+		return 0
+	}
+	return counter.Load()
 }
 
 // UpdateLastUsed updates only the last used timestamp for an API key.
@@ -319,12 +431,14 @@ func (s *Service) UpdateLastUsed(ctx context.Context, keyID string) error {
 	return s.store.UpdateAPIKeyLastUsed(ctx, keyID)
 }
 
-// RecordUsage updates last_used_at and increments both the lifetime counter
-// and the fixed-window request counter for the key. See
+// RecordUsage updates last_used_at and adds delta to both the lifetime
+// counter and the fixed-window request counter for the key. delta is the
+// number of requests being recorded, which is greater than 1 whenever
+// concurrent requests were coalesced into one flush. See
 // PostgresStore.RecordAPIKeyUsage for the atomic SQL and the window's
 // tumbling-reset semantics.
-func (s *Service) RecordUsage(ctx context.Context, keyID string) error {
-	return s.store.RecordAPIKeyUsage(ctx, keyID)
+func (s *Service) RecordUsage(ctx context.Context, keyID string, delta int64) error {
+	return s.store.RecordAPIKeyUsage(ctx, keyID, delta)
 }
 
 // computeEffectivePermissionsFromAuthCtx returns the subset of key permissions
diff --git a/internal/auth/service_apikeys_api.go b/internal/auth/service_apikeys_api.go
index ebcc424da..a0cd31183 100644
--- a/internal/auth/service_apikeys_api.go
+++ b/internal/auth/service_apikeys_api.go
@@ -13,18 +13,43 @@ import (
 // numbers) -- kept small since the summary card is a glance-level widget.
 const apiKeyUsageTopKeysLimit = 3
 
-// sortAPIKeysByActivity sorts in place by request_count_window desc, with
+// apiKeyActivity pairs a key with its effective (non-stale) window count so
+// the totals, the sort and the top-N cut all work off the same number
+// instead of each re-deriving it from the raw column.
+type apiKeyActivity struct {
+	key    *UserAPIKey
+	window int64
+}
+
+// sortAPIKeysByActivity sorts in place by effective window count desc, with
 // request_count_total desc as the tiebreaker. Extracted as a helper so
 // it can be unit-tested without going through the full service.
-func sortAPIKeysByActivity(keys []*UserAPIKey) {
-	sort.SliceStable(keys, func(i, j int) bool {
-		if keys[i].RequestCountWindow != keys[j].RequestCountWindow {
-			return keys[i].RequestCountWindow > keys[j].RequestCountWindow
+func sortAPIKeysByActivity(activity []apiKeyActivity) {
+	sort.SliceStable(activity, func(i, j int) bool {
+		if activity[i].window != activity[j].window {
+			return activity[i].window > activity[j].window
 		}
-		return keys[i].RequestCountTotal > keys[j].RequestCountTotal
+		return activity[i].key.RequestCountTotal > activity[j].key.RequestCountTotal
 	})
 }
 
+// effectiveWindowUsage returns the window counter and window start as they
+// should be reported to API consumers.
+//
+// The stored counter is only rewritten when the key's NEXT request arrives
+// (see PostgresStore.RecordAPIKeyUsage), so a key that stops being used
+// keeps its final window count on the row indefinitely. Reporting that
+// column verbatim would claim a key idle for months served N requests in
+// the current window. An expired window has no current activity, so it
+// reads as zero with no window start rather than a stale non-zero count.
+func effectiveWindowUsage(key *UserAPIKey, now time.Time) (int64, *time.Time) {
+	if key.RequestCountWindowStart == nil ||
+		!now.Before(key.RequestCountWindowStart.Add(apiKeyUsageWindow)) {
+		return 0, nil
+	}
+	return key.RequestCountWindow, key.RequestCountWindowStart
+}
+
 // API wrapper methods for API key operations
 // These methods return API-friendly types and handle type conversions
 
@@ -41,9 +66,10 @@ type APIKeyInfo struct {
 	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
 	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
 	// RequestCountWindowStart is when the current request_count_window
-	// began; nil means the key has never recorded a request. Exposed so
-	// consumers know exactly which period RequestCountWindow covers
-	// instead of assuming a true trailing "last 24h".
+	// began; nil means there is no current window, either because the key
+	// has never recorded a request or because its last window has closed.
+	// Exposed so consumers know exactly which period RequestCountWindow
+	// covers instead of assuming a true trailing "last 24h".
 	RequestCountWindowStart *time.Time   `json:"request_count_window_start,omitempty"`
 	ID                      string       `json:"id"`
 	Name                    string       `json:"name"`
@@ -51,7 +77,8 @@ type APIKeyInfo struct {
 	Permissions             []Permission `json:"permissions,omitempty"`
 	IsActive                bool         `json:"is_active"`
 	// Usage counters (issue #340/#344 deferred sub-task). RequestCountWindow
-	// is a fixed/tumbling window count, not a true rolling 24h total -- see
+	// is a fixed/tumbling window count, not a true rolling 24h total, and is
+	// zero once that window has closed -- see effectiveWindowUsage,
 	// PostgresStore.RecordAPIKeyUsage and RequestCountWindowStart above.
 	RequestCountTotal  int64 `json:"request_count_total"`
 	RequestCountWindow int64 `json:"request_count_window"`
@@ -72,7 +99,12 @@ type APIKeysUsageStatsTopKey struct {
 // calling user's own keys -- same scope as ListUserAPIKeysAPI.
 //
 // TotalRequestsWindow sums each key's fixed-window counter (see
-// PostgresStore.RecordAPIKeyUsage); it is NOT a true trailing-24h total.
+// PostgresStore.RecordAPIKeyUsage) across the keys whose window is still
+// open; it is NOT a true trailing-24h total, and the windows it sums are
+// not aligned with one another.
+//
+// TotalActive counts the keys the authentication path would accept, so a
+// key that is unrevoked but past its expiry is not counted.
 type APIKeysUsageStatsResponse struct {
 	TotalActive           int                       `json:"total_active"`
 	TotalRequestsWindow   int64                     `json:"total_requests_window"`
@@ -152,9 +184,13 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 		return nil, err
 	}
 
-	// Convert to API response
+	// Convert to API response. The window counter goes through
+	// effectiveWindowUsage so a key whose window has expired reports zero
+	// rather than the stale count still sitting on its row.
+	now := time.Now()
 	apiKeys := make([]*APIKeyInfo, 0, len(keys))
 	for _, key := range keys {
+		windowCount, windowStart := effectiveWindowUsage(key, now)
 		apiKeys = append(apiKeys, &APIKeyInfo{
 			ID:                      key.ID,
 			Name:                    key.Name,
@@ -165,8 +201,8 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 			LastUsedAt:              key.LastUsedAt,
 			IsActive:                key.IsActive,
 			RequestCountTotal:       key.RequestCountTotal,
-			RequestCountWindow:      key.RequestCountWindow,
-			RequestCountWindowStart: key.RequestCountWindowStart,
+			RequestCountWindow:      windowCount,
+			RequestCountWindowStart: windowStart,
 		})
 	}
 
@@ -180,46 +216,55 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 // separate DB round-trip -- ListUserAPIKeys already returns the per-key
 // counters from migration 000093.
 //
-// The "top keys" list is sorted by request_count_window descending, with
+// The "top keys" list is sorted by effective window count descending, with
 // total-lifetime as the tiebreaker so a long-running idle key doesn't
 // outrank an active one with the same window count. Up to
 // apiKeyUsageTopKeysLimit entries are surfaced; keys with zero window
 // activity are omitted rather than shown as an uninformative "top key".
+//
+// Window counts run through effectiveWindowUsage first: the raw column
+// keeps its last value until the key is used again, so summing it verbatim
+// would report requests from windows that closed arbitrarily long ago as
+// current activity.
+//
+// TotalActive uses validateAPIKeyStatus, the same predicate the
+// authentication path applies, so a key that is unrevoked but expired is
+// not counted as active here while the keys table below the summary card
+// shows it as "Expired".
 func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error) {
 	keys, err := s.ListUserAPIKeys(ctx, userID)
 	if err != nil {
 		return nil, err
 	}
 
+	now := time.Now()
 	resp := &APIKeysUsageStatsResponse{
 		TopKeys: []APIKeysUsageStatsTopKey{},
 	}
+	activity := make([]apiKeyActivity, 0, len(keys))
 	for _, k := range keys {
-		if k.IsActive {
+		windowCount, _ := effectiveWindowUsage(k, now)
+		if validateAPIKeyStatus(k) == nil {
 			resp.TotalActive++
 		}
-		resp.TotalRequestsWindow += k.RequestCountWindow
+		resp.TotalRequestsWindow += windowCount
 		resp.TotalRequestsLifetime += k.RequestCountTotal
+		activity = append(activity, apiKeyActivity{key: k, window: windowCount})
 	}
 
-	sorted := make([]*UserAPIKey, len(keys))
-	copy(sorted, keys)
-	sortAPIKeysByActivity(sorted)
+	sortAPIKeysByActivity(activity)
 
-	limit := apiKeyUsageTopKeysLimit
-	if len(sorted) < limit {
-		limit = len(sorted)
-	}
-	for i := 0; i < limit; i++ {
-		k := sorted[i]
-		if k.RequestCountWindow == 0 {
+	limit := min(apiKeyUsageTopKeysLimit, len(activity))
+	for i := range limit {
+		a := activity[i]
+		if a.window == 0 {
 			break
 		}
 		resp.TopKeys = append(resp.TopKeys, APIKeysUsageStatsTopKey{
-			ID:                 k.ID,
-			Name:               k.Name,
-			KeyPrefix:          k.KeyPrefix,
-			RequestCountWindow: k.RequestCountWindow,
+			ID:                 a.key.ID,
+			Name:               a.key.Name,
+			KeyPrefix:          a.key.KeyPrefix,
+			RequestCountWindow: a.window,
 		})
 	}
 
diff --git a/internal/auth/service_apikeys_api_test.go b/internal/auth/service_apikeys_api_test.go
index 408e78f21..b3c507b45 100644
--- a/internal/auth/service_apikeys_api_test.go
+++ b/internal/auth/service_apikeys_api_test.go
@@ -210,6 +210,50 @@ func TestService_ListUserAPIKeysAPI(t *testing.T) {
 		mockStore.AssertExpectations(t)
 	})
 
+	// Regression: the per-row "Requests (window)" cell must not show a count
+	// left over from a window that has already closed. The stored column
+	// keeps its value until the key's next request, so the read path is what
+	// has to zero it.
+	t.Run("zeroes an expired window and keeps a live one", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		stale := time.Now().Add(-48 * time.Hour)
+		fresh := time.Now().Add(-3 * time.Hour)
+		keys := []*UserAPIKey{
+			{ID: "stale", RequestCountWindow: 900, RequestCountTotal: 900, RequestCountWindowStart: &stale},
+			{ID: "live", RequestCountWindow: 11, RequestCountTotal: 40, RequestCountWindowStart: &fresh},
+			{ID: "never-used", RequestCountWindow: 0, RequestCountTotal: 0},
+		}
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.ListUserAPIKeysAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIListAPIKeysResponse)
+		require.True(t, ok)
+		require.Len(t, resp.APIKeys, 3)
+
+		// Expired window: no current activity, and no window start to point
+		// at a period that is over.
+		assert.Equal(t, int64(0), resp.APIKeys[0].RequestCountWindow)
+		assert.Nil(t, resp.APIKeys[0].RequestCountWindowStart)
+		// Lifetime is unaffected by the window expiring.
+		assert.Equal(t, int64(900), resp.APIKeys[0].RequestCountTotal)
+
+		// Live window passes through untouched.
+		assert.Equal(t, int64(11), resp.APIKeys[1].RequestCountWindow)
+		require.NotNil(t, resp.APIKeys[1].RequestCountWindowStart)
+		assert.Equal(t, fresh, *resp.APIKeys[1].RequestCountWindowStart)
+
+		// Never used: zero, with no window start.
+		assert.Equal(t, int64(0), resp.APIKeys[2].RequestCountWindow)
+		assert.Nil(t, resp.APIKeys[2].RequestCountWindowStart)
+	})
+
 	// #492: last_used_at must round-trip through ListUserAPIKeysAPI so the
 	// frontend can render "Last used" without a separate endpoint.
 	t.Run("last_used_at is present in response when key was used (issue #492)", func(t *testing.T) {
@@ -412,7 +456,7 @@ func TestService_ValidateUserAPIKeyAPI(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKeyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1").Return(nil).Maybe()
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).Return(nil).Maybe()
 
 		resultKey, resultUser, err := service.ValidateUserAPIKeyAPI(ctx, apiKey)
 
@@ -469,31 +513,47 @@ func TestService_ValidateUserAPIKeyAPI(t *testing.T) {
 
 func TestSortAPIKeysByActivity(t *testing.T) {
 	t.Run("sorts by window count descending", func(t *testing.T) {
-		keys := []*UserAPIKey{
-			{ID: "low", RequestCountWindow: 1, RequestCountTotal: 100},
-			{ID: "high", RequestCountWindow: 10, RequestCountTotal: 5},
-			{ID: "mid", RequestCountWindow: 5, RequestCountTotal: 50},
+		activity := []apiKeyActivity{
+			{key: &UserAPIKey{ID: "low", RequestCountTotal: 100}, window: 1},
+			{key: &UserAPIKey{ID: "high", RequestCountTotal: 5}, window: 10},
+			{key: &UserAPIKey{ID: "mid", RequestCountTotal: 50}, window: 5},
 		}
 
-		sortAPIKeysByActivity(keys)
+		sortAPIKeysByActivity(activity)
 
-		require.Len(t, keys, 3)
-		assert.Equal(t, "high", keys[0].ID)
-		assert.Equal(t, "mid", keys[1].ID)
-		assert.Equal(t, "low", keys[2].ID)
+		require.Len(t, activity, 3)
+		assert.Equal(t, "high", activity[0].key.ID)
+		assert.Equal(t, "mid", activity[1].key.ID)
+		assert.Equal(t, "low", activity[2].key.ID)
 	})
 
 	t.Run("uses lifetime total as tiebreaker", func(t *testing.T) {
-		keys := []*UserAPIKey{
-			{ID: "idle-high-lifetime", RequestCountWindow: 3, RequestCountTotal: 900},
-			{ID: "active-low-lifetime", RequestCountWindow: 3, RequestCountTotal: 10},
+		activity := []apiKeyActivity{
+			{key: &UserAPIKey{ID: "idle-high-lifetime", RequestCountTotal: 900}, window: 3},
+			{key: &UserAPIKey{ID: "active-low-lifetime", RequestCountTotal: 10}, window: 3},
+		}
+
+		sortAPIKeysByActivity(activity)
+
+		require.Len(t, activity, 2)
+		assert.Equal(t, "idle-high-lifetime", activity[0].key.ID)
+		assert.Equal(t, "active-low-lifetime", activity[1].key.ID)
+	})
+
+	t.Run("ranks by effective window, not the stale stored count", func(t *testing.T) {
+		// Regression for the stale-window bug: a key with a huge count left
+		// over from an expired window must not outrank a genuinely active
+		// key. The caller zeroes the expired window via effectiveWindowUsage
+		// before sorting, so the sort sees window=0 for the stale key.
+		activity := []apiKeyActivity{
+			{key: &UserAPIKey{ID: "stale-but-huge", RequestCountWindow: 9999, RequestCountTotal: 9999}, window: 0},
+			{key: &UserAPIKey{ID: "currently-active", RequestCountWindow: 4, RequestCountTotal: 4}, window: 4},
 		}
 
-		sortAPIKeysByActivity(keys)
+		sortAPIKeysByActivity(activity)
 
-		require.Len(t, keys, 2)
-		assert.Equal(t, "idle-high-lifetime", keys[0].ID)
-		assert.Equal(t, "active-low-lifetime", keys[1].ID)
+		require.Len(t, activity, 2)
+		assert.Equal(t, "currently-active", activity[0].key.ID)
 	})
 }
 
@@ -505,11 +565,12 @@ func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 		t.Cleanup(func() { mockStore.AssertExpectations(t) })
 		service := &Service{store: mockStore}
 
+		fresh := time.Now().Add(-1 * time.Hour)
 		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
 		keys := []*UserAPIKey{
-			{ID: "key-1", Name: "Busy", KeyPrefix: "aaaa1111", IsActive: true, RequestCountWindow: 30, RequestCountTotal: 300},
-			{ID: "key-2", Name: "Medium", KeyPrefix: "bbbb2222", IsActive: true, RequestCountWindow: 12, RequestCountTotal: 120},
-			{ID: "key-3", Name: "Quiet", KeyPrefix: "cccc3333", IsActive: false, RequestCountWindow: 3, RequestCountTotal: 60},
+			{ID: "key-1", Name: "Busy", KeyPrefix: "aaaa1111", IsActive: true, RequestCountWindow: 30, RequestCountTotal: 300, RequestCountWindowStart: &fresh},
+			{ID: "key-2", Name: "Medium", KeyPrefix: "bbbb2222", IsActive: true, RequestCountWindow: 12, RequestCountTotal: 120, RequestCountWindowStart: &fresh},
+			{ID: "key-3", Name: "Quiet", KeyPrefix: "cccc3333", IsActive: false, RequestCountWindow: 3, RequestCountTotal: 60, RequestCountWindowStart: &fresh},
 			{ID: "key-4", Name: "Idle", KeyPrefix: "dddd4444", IsActive: true, RequestCountWindow: 0, RequestCountTotal: 5},
 		}
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
@@ -557,6 +618,73 @@ func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 		assert.Empty(t, resp.TopKeys)
 	})
 
+	// Regression: the window counter on an api_keys row is only rewritten by
+	// the key's NEXT request, so a key that went idle keeps its last window
+	// count forever. Summing that column verbatim reported requests from a
+	// window that closed arbitrarily long ago as current activity.
+	t.Run("excludes counts from expired windows", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		stale := time.Now().Add(-30 * 24 * time.Hour)
+		fresh := time.Now().Add(-2 * time.Hour)
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		keys := []*UserAPIKey{
+			// Hammered a month ago, untouched since: its window is long gone.
+			{ID: "stale", Name: "Stale", KeyPrefix: "aaaa1111", IsActive: true, RequestCountWindow: 5000, RequestCountTotal: 5000, RequestCountWindowStart: &stale},
+			// Genuinely active inside the current window.
+			{ID: "active", Name: "Active", KeyPrefix: "bbbb2222", IsActive: true, RequestCountWindow: 7, RequestCountTotal: 7, RequestCountWindowStart: &fresh},
+		}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		// Only the live window counts; the 5000 stale requests are not
+		// current activity. Lifetime still includes them.
+		assert.Equal(t, int64(7), resp.TotalRequestsWindow)
+		assert.Equal(t, int64(5007), resp.TotalRequestsLifetime)
+		// The stale key must not be listed as "most active", and must not
+		// outrank the key that is actually being used.
+		require.Len(t, resp.TopKeys, 1)
+		assert.Equal(t, "active", resp.TopKeys[0].ID)
+		assert.Equal(t, int64(7), resp.TopKeys[0].RequestCountWindow)
+	})
+
+	// Regression: TotalActive counted any unrevoked key, so a key past its
+	// expiry was summarized as "active" while the keys table right below the
+	// summary card rendered the same key as "Expired". The authentication
+	// path (validateAPIKeyStatus / GetAPIKeyByHash) already treats an
+	// expired key as unusable.
+	t.Run("does not count expired keys as active", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		expired := time.Now().Add(-1 * time.Hour)
+		future := time.Now().Add(24 * time.Hour)
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		keys := []*UserAPIKey{
+			{ID: "expired", IsActive: true, ExpiresAt: &expired},
+			{ID: "revoked", IsActive: false},
+			{ID: "live", IsActive: true, ExpiresAt: &future},
+			{ID: "no-expiry", IsActive: true},
+		}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		assert.Equal(t, 2, resp.TotalActive)
+	})
+
 	t.Run("returns empty stats when user has no keys", func(t *testing.T) {
 		mockStore := new(MockStore)
 		t.Cleanup(func() { mockStore.AssertExpectations(t) })
diff --git a/internal/auth/service_apikeys_test.go b/internal/auth/service_apikeys_test.go
index a9457190f..2024b2e9b 100644
--- a/internal/auth/service_apikeys_test.go
+++ b/internal/auth/service_apikeys_test.go
@@ -4,6 +4,8 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/base64"
+	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -514,7 +516,7 @@ func TestService_ValidateUserAPIKey(t *testing.T) {
 		// silently passes) if ValidateUserAPIKey ever stops recording usage,
 		// and so we don't have to busy-sleep waiting for the async goroutine.
 		usageRecorded := make(chan struct{}, 1)
-		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1").
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).
 			Run(func(mock.Arguments) { usageRecorded <- struct{}{} }).
 			Return(nil).Once()
 
@@ -726,9 +728,9 @@ func TestService_RecordUsage(t *testing.T) {
 		mockStore := new(MockStore)
 		service := &Service{store: mockStore}
 
-		mockStore.On("RecordAPIKeyUsage", ctx, "key-1").Return(nil)
+		mockStore.On("RecordAPIKeyUsage", ctx, "key-1", mock.Anything).Return(nil)
 
-		err := service.RecordUsage(ctx, "key-1")
+		err := service.RecordUsage(ctx, "key-1", 1)
 		require.NoError(t, err)
 		mockStore.AssertExpectations(t)
 	})
@@ -737,14 +739,112 @@ func TestService_RecordUsage(t *testing.T) {
 		mockStore := new(MockStore)
 		service := &Service{store: mockStore}
 
-		mockStore.On("RecordAPIKeyUsage", ctx, "key-1").Return(assert.AnError)
+		mockStore.On("RecordAPIKeyUsage", ctx, "key-1", mock.Anything).Return(assert.AnError)
 
-		err := service.RecordUsage(ctx, "key-1")
+		err := service.RecordUsage(ctx, "key-1", 1)
 		assert.Error(t, err)
 		mockStore.AssertExpectations(t)
 	})
 }
 
+// Regression: singleflight collapses concurrent flushes for the same key
+// into one DB write. Writing a fixed "+1" inside that flush silently dropped
+// every request that arrived while a write was in flight, undercounting the
+// busiest keys -- precisely the keys the usage stats exist to surface. The
+// pending count is accumulated first and the flush writes the whole delta.
+func TestService_FlushPendingUsage(t *testing.T) {
+	t.Run("writes the whole coalesced delta in one call", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", int64(5)).Return(nil).Once()
+
+		for range 5 {
+			service.addPendingUsage("key-1")
+		}
+		service.flushPendingUsage("key-1")
+	})
+
+	t.Run("does not write when nothing is pending", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		service.flushPendingUsage("never-seen-key")
+		mockStore.AssertNotCalled(t, "RecordAPIKeyUsage", mock.Anything, mock.Anything, mock.Anything)
+	})
+
+	t.Run("leaves requests booked during the write for the next round", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		// A request that lands while the write is in flight must still be
+		// pending afterwards -- recordUsageAsync's loop picks it up.
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", int64(2)).
+			Run(func(mock.Arguments) { service.addPendingUsage("key-1") }).
+			Return(nil).Once()
+
+		service.addPendingUsage("key-1")
+		service.addPendingUsage("key-1")
+		service.flushPendingUsage("key-1")
+
+		assert.Equal(t, int64(1), service.peekPendingUsage("key-1"))
+	})
+
+	t.Run("drops the delta on a store error rather than retrying forever", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", int64(3)).
+			Return(assert.AnError).Once()
+
+		for range 3 {
+			service.addPendingUsage("key-1")
+		}
+		service.flushPendingUsage("key-1")
+
+		assert.Equal(t, int64(0), service.peekPendingUsage("key-1"))
+	})
+}
+
+// Every request must be booked before the flush goroutine starts, so a
+// request is never lost to a flush that had already drained the counter.
+func TestService_RecordUsageAsync_CountsConcurrentRequests(t *testing.T) {
+	mockStore := new(MockStore)
+	service := &Service{store: mockStore}
+
+	const requests = 50
+	var recorded atomic.Int64
+	done := make(chan struct{})
+	mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).
+		Run(func(args mock.Arguments) {
+			if recorded.Add(args.Get(2).(int64)) == requests {
+				close(done)
+			}
+		}).
+		Return(nil).Maybe()
+
+	var wg sync.WaitGroup
+	for range requests {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			service.recordUsageAsync("key-1")
+		}()
+	}
+	wg.Wait()
+
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatalf("only %d of %d requests were recorded", recorded.Load(), requests)
+	}
+	assert.Equal(t, int64(requests), recorded.Load())
+}
+
 func TestService_ComputeEffectivePermissions(t *testing.T) {
 	ctx := context.Background()
 
@@ -902,7 +1002,7 @@ func TestService_HasAPIKeyPermissionAPI(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(keyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1").Return(nil).Maybe()
+		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).Return(nil).Maybe()
 		mockStore.On("GetGroup", ctx, userGrpID).Return(userGrp(), nil)
 		return service
 	}
@@ -1057,7 +1157,7 @@ func TestValidateUserAPIKey_UpdateLastUsedPanicIsRecovered(t *testing.T) {
 	// done is closed by the Run callback immediately before panicking so the
 	// test can wait for goroutine execution without time.Sleep.
 	done := make(chan struct{})
-	mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-panic").
+	mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-panic", mock.Anything).
 		Run(func(args mock.Arguments) {
 			close(done)
 			panic("injected panic for #672 regression test")
diff --git a/internal/auth/service_security_test.go b/internal/auth/service_security_test.go
index 62c80b9ce..864a22ba9 100644
--- a/internal/auth/service_security_test.go
+++ b/internal/auth/service_security_test.go
@@ -254,7 +254,7 @@ func TestValidateUserAPIKey_LastUsedSingleflight(t *testing.T) {
 	done := make(chan struct{})
 	mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKey, nil).Maybe()
 	mockStore.On("GetUserByID", ctx, user.ID).Return(user, nil).Maybe()
-	mockStore.On("RecordAPIKeyUsage", mock.Anything, keyID).
+	mockStore.On("RecordAPIKeyUsage", mock.Anything, keyID, mock.Anything).
 		Run(func(args mock.Arguments) { close(done) }).
 		Return(nil).Once()
 
diff --git a/internal/auth/store_postgres.go b/internal/auth/store_postgres.go
index 2779d8eec..9c7b38064 100644
--- a/internal/auth/store_postgres.go
+++ b/internal/auth/store_postgres.go
@@ -889,48 +889,59 @@ func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string)
 	return nil
 }
 
-// RecordAPIKeyUsage atomically updates last_used_at, increments
-// request_count_total, and increments-or-resets request_count_window based
-// on whether the current window is still within 24h of its start.
+// RecordAPIKeyUsage atomically updates last_used_at, adds delta to
+// request_count_total, and adds-or-resets request_count_window based on
+// whether the current window is still within apiKeyUsageWindow of its start.
+//
+// delta is the number of requests being recorded in this flush. The auth hot
+// path coalesces concurrent requests for the same key into a single write
+// (see Service.recordUsageAsync), so delta is frequently greater than 1 and
+// must be added rather than treated as a single increment.
 //
 // request_count_window is a FIXED/TUMBLING window counter, not a true
 // trailing-24h rolling count: the single UPDATE does the window decision
 // inline --
-//   - if window_start IS NULL OR (NOW() - window_start) >= 24h, start a
-//     fresh window (window_start = NOW(), count = 1) -- this DISCARDS
-//     whatever count the previous window had, even if some of those
-//     requests happened within the preceding 24h of NOW().
-//   - otherwise increment the existing count.
+//   - if window_start IS NULL OR (NOW() - window_start) >= apiKeyUsageWindow,
+//     start a fresh window (window_start = NOW(), count = delta) -- this
+//     DISCARDS whatever count the previous window had, even if some of those
+//     requests happened within the preceding window-length of NOW().
+//   - otherwise add delta to the existing count.
+//
+// The window length is passed in from apiKeyUsageWindow rather than written
+// as a SQL literal so the write path and the API read path (which zeroes an
+// expired window, see effectiveWindowUsage) cannot drift apart.
 //
-// A request made moments before a window resets is therefore dropped from
-// the count as soon as the next request starts a new window; an idle key's
-// stale count also lingers unchanged until its next request. Callers that
+// An idle key's stale count lingers on the row unchanged until its next
+// request; the read path is responsible for not reporting it. Callers that
 // need the actual period covered should read request_count_window_start
 // rather than assuming "requests in the last 24h".
 //
 // Doing it in one statement keeps the update atomic per row, so two
-// concurrent calls can't both see "stale window" and reset to 1 in
-// parallel -- pgx serializes updates to the same row.
-func (s *PostgresStore) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
+// concurrent calls can't both see "stale window" and reset in parallel --
+// pgx serializes updates to the same row.
+func (s *PostgresStore) RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error {
+	if delta <= 0 {
+		return fmt.Errorf("invalid API key usage delta %d: must be positive", delta)
+	}
 	query := `
 		UPDATE api_keys
 		SET last_used_at = NOW(),
-		    request_count_total = request_count_total + 1,
+		    request_count_total = request_count_total + $2,
 		    request_count_window = CASE
 		        WHEN request_count_window_start IS NULL
-		             OR NOW() - request_count_window_start >= INTERVAL '24 hours'
-		        THEN 1
-		        ELSE request_count_window + 1
+		             OR NOW() - request_count_window_start >= make_interval(secs => $3)
+		        THEN $2
+		        ELSE request_count_window + $2
 		    END,
 		    request_count_window_start = CASE
 		        WHEN request_count_window_start IS NULL
-		             OR NOW() - request_count_window_start >= INTERVAL '24 hours'
+		             OR NOW() - request_count_window_start >= make_interval(secs => $3)
 		        THEN NOW()
 		        ELSE request_count_window_start
 		    END
 		WHERE id = $1
 	`
-	result, err := s.db.Exec(ctx, query, keyID)
+	result, err := s.db.Exec(ctx, query, keyID, delta, apiKeyUsageWindow.Seconds())
 	if err != nil {
 		return fmt.Errorf("failed to record API key usage: %w", err)
 	}
diff --git a/internal/auth/store_postgres_pgxmock_test.go b/internal/auth/store_postgres_pgxmock_test.go
index 01a447253..02f8d9692 100644
--- a/internal/auth/store_postgres_pgxmock_test.go
+++ b/internal/auth/store_postgres_pgxmock_test.go
@@ -538,22 +538,51 @@ func TestPGXMock_RecordAPIKeyUsage_Success(t *testing.T) {
 	store := NewPostgresStore(mock)
 
 	mock.ExpectExec(`(?s)UPDATE api_keys\s+SET last_used_at = NOW\(\),.*WHERE id = \$1`).
-		WithArgs("key-1").
+		WithArgs("key-1", int64(1), apiKeyUsageWindow.Seconds()).
+		WillReturnResult(pgxmock.NewResult("UPDATE", 1))
+
+	err := store.RecordAPIKeyUsage(context.Background(), "key-1", 1)
+	assert.NoError(t, err)
+}
+
+// A flush that coalesced several concurrent requests must add the whole
+// delta, not a hardcoded 1. Asserting the bound argument is what catches a
+// regression to "+ 1" in the SQL.
+func TestPGXMock_RecordAPIKeyUsage_CoalescedDelta(t *testing.T) {
+	mock := newAuthPgxMock(t)
+	store := NewPostgresStore(mock)
+
+	mock.ExpectExec(`(?s)request_count_total = request_count_total \+ \$2.*request_count_window \+ \$2`).
+		WithArgs("key-1", int64(42), apiKeyUsageWindow.Seconds()).
 		WillReturnResult(pgxmock.NewResult("UPDATE", 1))
 
-	err := store.RecordAPIKeyUsage(context.Background(), "key-1")
+	err := store.RecordAPIKeyUsage(context.Background(), "key-1", 42)
 	assert.NoError(t, err)
 }
 
+// A non-positive delta is a caller bug, not something to paper over with a
+// no-op UPDATE: no statement is issued and the error is explicit.
+func TestPGXMock_RecordAPIKeyUsage_RejectsNonPositiveDelta(t *testing.T) {
+	mock := newAuthPgxMock(t)
+	store := NewPostgresStore(mock)
+
+	for _, delta := range []int64{0, -1} {
+		err := store.RecordAPIKeyUsage(context.Background(), "key-1", delta)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "must be positive")
+	}
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
 func TestPGXMock_RecordAPIKeyUsage_NotFound(t *testing.T) {
 	mock := newAuthPgxMock(t)
 	store := NewPostgresStore(mock)
 
 	mock.ExpectExec(`(?s)UPDATE api_keys\s+SET last_used_at = NOW\(\),.*WHERE id = \$1`).
-		WithArgs("missing-key").
+		WithArgs("missing-key", int64(1), apiKeyUsageWindow.Seconds()).
 		WillReturnResult(pgxmock.NewResult("UPDATE", 0))
 
-	err := store.RecordAPIKeyUsage(context.Background(), "missing-key")
+	err := store.RecordAPIKeyUsage(context.Background(), "missing-key", 1)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "API key not found")
 }
@@ -563,10 +592,10 @@ func TestPGXMock_RecordAPIKeyUsage_ExecError(t *testing.T) {
 	store := NewPostgresStore(mock)
 
 	mock.ExpectExec(`(?s)UPDATE api_keys\s+SET last_used_at = NOW\(\),.*WHERE id = \$1`).
-		WithArgs("key-1").
+		WithArgs("key-1", int64(1), apiKeyUsageWindow.Seconds()).
 		WillReturnError(errors.New("db down"))
 
-	err := store.RecordAPIKeyUsage(context.Background(), "key-1")
+	err := store.RecordAPIKeyUsage(context.Background(), "key-1", 1)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "failed to record API key usage")
 }
diff --git a/internal/auth/test_helpers.go b/internal/auth/test_helpers.go
index fdf53452a..8f519ad1e 100644
--- a/internal/auth/test_helpers.go
+++ b/internal/auth/test_helpers.go
@@ -217,8 +217,8 @@ func (m *MockStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) erro
 	return args.Error(0)
 }
 
-func (m *MockStore) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
-	args := m.Called(ctx, keyID)
+func (m *MockStore) RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error {
+	args := m.Called(ctx, keyID, delta)
 	return args.Error(0)
 }
 
diff --git a/internal/auth/types.go b/internal/auth/types.go
index d098fcd7c..f0554af0b 100644
--- a/internal/auth/types.go
+++ b/internal/auth/types.go
@@ -81,10 +81,16 @@ type UserAPIKey struct {
 	// Usage counters (issue #340/#344 deferred sub-task -- migration 000093).
 	// Both default to 0 for legacy rows. RequestCountWindow is a
 	// FIXED/TUMBLING window count, not a true trailing-24h rolling count:
-	// the store's RecordAPIKeyUsage path resets it (and RequestCountWindowStart)
-	// to a fresh window once the existing window is older than 24h, so a
-	// request made just before that reset is dropped from the count as soon
-	// as the next request starts a new window. RequestCountWindowStart is
+	// the store's RecordAPIKeyUsage path restarts it (and
+	// RequestCountWindowStart) once the existing window is older than
+	// apiKeyUsageWindow, so a request made just before that reset is dropped
+	// from the count as soon as the next request starts a new window.
+	//
+	// These are the RAW column values: because the reset only happens on the
+	// key's next request, a key that went idle still carries its closed
+	// window's count here. The API layer zeroes an expired window before
+	// reporting it (see effectiveWindowUsage) -- do not surface these fields
+	// to callers without going through it. RequestCountWindowStart is
 	// exposed so API consumers can see exactly which period the count
 	// covers instead of assuming "last 24h".
 	RequestCountTotal       int64      `json:"request_count_total" dynamodbav:"RequestCountTotal"`
diff --git a/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
index 4cd54f080..716a2a1a6 100644
--- a/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
+++ b/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
@@ -7,7 +7,7 @@
 --
 --   * request_count_total        -- lifetime count since the key was created.
 --   * request_count_window       -- count since request_count_window_start;
---                                  reset to 1 (with a fresh window_start)
+--                                  restarted (with a fresh window_start)
 --                                  the first time RecordAPIKeyUsage sees
 --                                  the window older than 24h. This is a
 --                                  FIXED/TUMBLING window, not a true
@@ -16,6 +16,13 @@
 --                                  discarded from the count as soon as the
 --                                  next request starts a new window. See
 --                                  store_postgres.go RecordAPIKeyUsage.
+--                                  NOTE the restart only happens on the
+--                                  key's NEXT request, so an idle key keeps
+--                                  its closed window's count in this column
+--                                  indefinitely. Readers must treat a
+--                                  window older than 24h as zero -- see
+--                                  service_apikeys_api.go
+--                                  effectiveWindowUsage.
 --   * request_count_window_start -- the timestamp the current window
 --                                  started at; NULL until the first
 --                                  request after this migration runs.
diff --git a/internal/mocks/stores.go b/internal/mocks/stores.go
index 0cc4ccd43..37c25b82c 100644
--- a/internal/mocks/stores.go
+++ b/internal/mocks/stores.go
@@ -819,8 +819,8 @@ func (m *MockAuthStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string)
 }
 
 // RecordAPIKeyUsage mocks the RecordAPIKeyUsage operation.
-func (m *MockAuthStore) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
-	args := m.Called(ctx, keyID)
+func (m *MockAuthStore) RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error {
+	args := m.Called(ctx, keyID, delta)
 	return args.Error(0)
 }
 
diff --git a/internal/server/health_test.go b/internal/server/health_test.go
index 87e793c1b..0e3a8b11e 100644
--- a/internal/server/health_test.go
+++ b/internal/server/health_test.go
@@ -120,7 +120,7 @@ func (m *mockAuthStoreForHealth) UpdateAPIKeyLastUsed(ctx context.Context, keyID
 	return nil
 }
 
-func (m *mockAuthStoreForHealth) RecordAPIKeyUsage(ctx context.Context, keyID string) error {
+func (m *mockAuthStoreForHealth) RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error {
 	return nil
 }
 

From f072d5d9941ed87728cf31d6b821d48b3afd37f9 Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 19:40:50 +0200
Subject: [PATCH 4/8] fix(auth,frontend): split API-key store file, guard stale
 summary loads

Addresses the two still-open CodeRabbit findings on this PR.

store_postgres.go was past the project's 500-line ceiling and this PR
pushed it further. Its API-key surface moves to store_postgres_apikeys.go
(856 + 301 lines). Pure move: no query, scanning or signature changes.

loadApiKeysUsageStats could render a stale result. Concurrent refreshes
resolve in arbitrary order, so a slow earlier request could overwrite a
newer summary, or paint its error over a summary that had loaded fine. A
generation counter makes a load a no-op once a newer one has started, on
both the success and the failure path.

Adds apikeys-usage.test.ts, which the summary module had been missing
entirely: render path, top-keys list, markup-in-key-name staying literal
text, count-abbreviation boundaries, the error path, and both ordering
guards. The two ordering tests fail against the unguarded loader.
---
 frontend/src/__tests__/apikeys-usage.test.ts | 207 +++++++++++++
 frontend/src/apikeys_usage.ts                |  11 +
 internal/auth/store_postgres.go              | 288 -----------------
 internal/auth/store_postgres_apikeys.go      | 305 +++++++++++++++++++
 4 files changed, 523 insertions(+), 288 deletions(-)
 create mode 100644 frontend/src/__tests__/apikeys-usage.test.ts
 create mode 100644 internal/auth/store_postgres_apikeys.go

diff --git a/frontend/src/__tests__/apikeys-usage.test.ts b/frontend/src/__tests__/apikeys-usage.test.ts
new file mode 100644
index 000000000..2d6c640aa
--- /dev/null
+++ b/frontend/src/__tests__/apikeys-usage.test.ts
@@ -0,0 +1,207 @@
+/**
+ * Tests for src/apikeys_usage.ts -- the API keys section summary card.
+ *
+ * The module had no direct coverage when it was introduced; these tests
+ * cover the render path, the count formatting boundaries, the error path,
+ * and the out-of-order-response guard.
+ */
+import { loadApiKeysUsageStats, renderApiKeysUsageSummary } from '../apikeys_usage';
+import type { APIKeysUsageStats } from '../api/types';
+import * as api from '../api';
+
+jest.mock('../api');
+
+const mockedApi = api as jest.Mocked<typeof api>;
+
+function setupContainer(): HTMLElement {
+  document.body.innerHTML = '<div id="apikeys-usage-summary"></div>';
+  return document.getElementById('apikeys-usage-summary') as HTMLElement;
+}
+
+function stats(overrides: Partial<APIKeysUsageStats> = {}): APIKeysUsageStats {
+  return {
+    total_active: 2,
+    total_requests_window: 42,
+    total_requests_lifetime: 1234,
+    top_keys: [],
+    ...overrides,
+  };
+}
+
+function tileValues(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('.apikeys-usage-tile-value')).map(
+    el => el.textContent ?? ''
+  );
+}
+
+describe('renderApiKeysUsageSummary', () => {
+  test('renders the three summary tiles', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(stats());
+
+    expect(tileValues(container)).toEqual(['2', '42', '1.2k']);
+  });
+
+  test('renders the top-keys list when keys have window activity', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(
+      stats({
+        top_keys: [
+          { id: 'key-1', name: 'Busy', key_prefix: 'aaaa1111', request_count_window: 30 },
+          { id: 'key-2', name: 'Medium', key_prefix: 'bbbb2222', request_count_window: 12 },
+        ],
+      })
+    );
+
+    const items = container.querySelectorAll('.apikeys-usage-top-list li');
+    expect(items).toHaveLength(2);
+    expect(items[0]?.querySelector('strong')?.textContent).toBe('Busy');
+    expect(items[0]?.querySelector('code')?.textContent).toBe('aaaa1111...');
+    expect(items[0]?.querySelector('.apikeys-usage-top-count')?.textContent).toBe('30 req');
+  });
+
+  test('omits the top-keys section when there is no window activity', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(stats({ top_keys: [] }));
+
+    expect(container.querySelector('.apikeys-usage-top-list')).toBeNull();
+    expect(container.querySelector('.apikeys-usage-top-heading')).toBeNull();
+  });
+
+  // The card is built with createElement/textContent rather than innerHTML,
+  // so a key name containing markup must land as literal text.
+  test('does not interpret markup in a key name as HTML', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(
+      stats({
+        top_keys: [
+          {
+            id: 'key-1',
+            name: '<img src=x onerror=alert(1)>',
+            key_prefix: '<script>',
+            request_count_window: 1,
+          },
+        ],
+      })
+    );
+
+    expect(container.querySelector('img')).toBeNull();
+    expect(container.querySelector('script')).toBeNull();
+    expect(container.querySelector('.apikeys-usage-top-list strong')?.textContent).toBe(
+      '<img src=x onerror=alert(1)>'
+    );
+  });
+
+  test('replaces previous content instead of appending on re-render', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(stats());
+    renderApiKeysUsageSummary(stats());
+
+    expect(container.querySelectorAll('.apikeys-usage-summary')).toHaveLength(1);
+  });
+
+  test.each([
+    [0, '0'],
+    [999, '999'],
+    [1000, '1k'],
+    [1500, '1.5k'],
+    [10_000, '10k'],
+    // Rounds up into the next unit rather than emitting "1000k".
+    [999_999, '1.0M'],
+    [1_500_000, '1.5M'],
+    [10_000_000, '10M'],
+    // Garbage in must not render "NaN" to the user.
+    [Number.NaN, '0'],
+    [-5, '0'],
+  ])('formats a window total of %p as %p', (value, expected) => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(stats({ total_requests_window: value }));
+
+    expect(tileValues(container)[1]).toBe(expected);
+  });
+});
+
+describe('loadApiKeysUsageStats', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('renders the fetched summary', async () => {
+    const container = setupContainer();
+    mockedApi.getApiKeysUsageStats.mockResolvedValue(stats({ total_active: 7 }));
+
+    await loadApiKeysUsageStats();
+
+    expect(tileValues(container)[0]).toBe('7');
+  });
+
+  test('shows an inline error without throwing when the fetch fails', async () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    const container = setupContainer();
+    mockedApi.getApiKeysUsageStats.mockRejectedValue(new Error('boom'));
+
+    await expect(loadApiKeysUsageStats()).resolves.toBeUndefined();
+
+    expect(container.querySelector('p.error')?.textContent).toBe('Failed to load usage summary');
+    consoleError.mockRestore();
+  });
+
+  // Regression: refreshes can resolve out of order. A slow earlier request
+  // must not overwrite the result of a later one.
+  test('ignores a stale response that resolves after a newer one', async () => {
+    const container = setupContainer();
+
+    let resolveFirst: (value: APIKeysUsageStats) => void = () => undefined;
+    const first = new Promise<APIKeysUsageStats>(resolve => {
+      resolveFirst = resolve;
+    });
+    mockedApi.getApiKeysUsageStats.mockReturnValueOnce(first);
+    mockedApi.getApiKeysUsageStats.mockResolvedValueOnce(stats({ total_active: 99 }));
+
+    const stalePending = loadApiKeysUsageStats();
+    await loadApiKeysUsageStats();
+    expect(tileValues(container)[0]).toBe('99');
+
+    resolveFirst(stats({ total_active: 1 }));
+    await stalePending;
+
+    expect(tileValues(container)[0]).toBe('99');
+  });
+
+  // Same ordering guard on the failure path: a stale rejection must not
+  // paint an error over a summary that loaded successfully.
+  test('ignores a stale rejection that lands after a newer success', async () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    const container = setupContainer();
+
+    let rejectFirst: (reason: Error) => void = () => undefined;
+    const first = new Promise<APIKeysUsageStats>((_, reject) => {
+      rejectFirst = reject;
+    });
+    mockedApi.getApiKeysUsageStats.mockReturnValueOnce(first);
+    mockedApi.getApiKeysUsageStats.mockResolvedValueOnce(stats({ total_active: 5 }));
+
+    const stalePending = loadApiKeysUsageStats();
+    await loadApiKeysUsageStats();
+
+    rejectFirst(new Error('slow failure'));
+    await stalePending;
+
+    expect(container.querySelector('p.error')).toBeNull();
+    expect(tileValues(container)[0]).toBe('5');
+    consoleError.mockRestore();
+  });
+
+  test('is a no-op when the summary container is absent', async () => {
+    document.body.innerHTML = '';
+
+    await expect(loadApiKeysUsageStats()).resolves.toBeUndefined();
+    expect(mockedApi.getApiKeysUsageStats).not.toHaveBeenCalled();
+  });
+});
diff --git a/frontend/src/apikeys_usage.ts b/frontend/src/apikeys_usage.ts
index 3b412f419..56c54b3ed 100644
--- a/frontend/src/apikeys_usage.ts
+++ b/frontend/src/apikeys_usage.ts
@@ -12,6 +12,14 @@ import * as api from './api';
 import type { APIKeysUsageStats } from './api/types';
 import { showSkeletonBlock, teardownSkeleton } from './lib/skeleton';
 
+/**
+ * Generation counter for in-flight summary loads. Refreshes can resolve out
+ * of order, so a load only touches the DOM if it is still the newest one --
+ * otherwise a slow older request would overwrite a newer result, or paint an
+ * error over a summary that loaded fine.
+ */
+let usageStatsGeneration = 0;
+
 /**
  * Load and render the section-level usage summary (totals + top keys).
  * Fails closed: on error the summary slot shows an inline message and
@@ -20,12 +28,15 @@ import { showSkeletonBlock, teardownSkeleton } from './lib/skeleton';
 export async function loadApiKeysUsageStats(): Promise<void> {
   const container = document.getElementById('apikeys-usage-summary');
   if (!container) return;
+  const generation = ++usageStatsGeneration;
   showSkeletonBlock(container, '100%', '4rem');
   try {
     const stats = await api.getApiKeysUsageStats();
+    if (generation !== usageStatsGeneration) return;
     renderApiKeysUsageSummary(stats);
   } catch (error) {
     console.error('Failed to load API keys usage stats:', error);
+    if (generation !== usageStatsGeneration) return;
     teardownSkeleton(container);
     const p = document.createElement('p');
     p.className = 'error';
diff --git a/internal/auth/store_postgres.go b/internal/auth/store_postgres.go
index 9c7b38064..97d8675a3 100644
--- a/internal/auth/store_postgres.go
+++ b/internal/auth/store_postgres.go
@@ -729,244 +729,6 @@ func (s *PostgresStore) CleanupExpiredSessions(ctx context.Context) error {
 	return nil
 }
 
-// ==========================================
-// API KEY OPERATIONS
-// ==========================================
-
-// CreateAPIKey creates a new API key.
-func (s *PostgresStore) CreateAPIKey(ctx context.Context, key *UserAPIKey) error {
-	// Generate UUID if not provided
-	if key.ID == "" {
-		key.ID = uuid.New().String()
-	}
-
-	// Set timestamps
-	key.CreatedAt = time.Now()
-
-	// Marshal permissions to JSONB
-	permissionsJSON, err := json.Marshal(key.Permissions)
-	if err != nil {
-		return fmt.Errorf("failed to marshal permissions: %w", err)
-	}
-
-	query := `
-		INSERT INTO api_keys (
-			id, user_id, name, key_prefix, key_hash, permissions,
-			is_active, expires_at, created_at, last_used_at
-		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
-	`
-
-	_, err = s.db.Exec(ctx, query,
-		key.ID,
-		key.UserID,
-		key.Name,
-		key.KeyPrefix,
-		key.KeyHash,
-		permissionsJSON,
-		key.IsActive,
-		key.ExpiresAt,
-		key.CreatedAt,
-		key.LastUsedAt,
-	)
-
-	if err != nil {
-		return fmt.Errorf("failed to create API key: %w", err)
-	}
-
-	return nil
-}
-
-// GetAPIKeyByID retrieves an API key by ID.
-func (s *PostgresStore) GetAPIKeyByID(ctx context.Context, keyID string) (*UserAPIKey, error) {
-	query := `
-		SELECT id, user_id, name, key_prefix, key_hash, permissions,
-		       is_active, expires_at, created_at, last_used_at,
-		       request_count_total, request_count_window, request_count_window_start
-		FROM api_keys
-		WHERE id = $1
-	`
-
-	return s.scanAPIKey(s.db.QueryRow(ctx, query, keyID))
-}
-
-// GetAPIKeyByHash retrieves an API key by hash.
-func (s *PostgresStore) GetAPIKeyByHash(ctx context.Context, keyHash string) (*UserAPIKey, error) {
-	query := `
-		SELECT id, user_id, name, key_prefix, key_hash, permissions,
-		       is_active, expires_at, created_at, last_used_at,
-		       request_count_total, request_count_window, request_count_window_start
-		FROM api_keys
-		WHERE key_hash = $1 AND is_active = true
-		  AND (expires_at IS NULL OR expires_at > NOW())
-	`
-
-	return s.scanAPIKey(s.db.QueryRow(ctx, query, keyHash))
-}
-
-// ListAPIKeysByUser lists all API keys for a user.
-func (s *PostgresStore) ListAPIKeysByUser(ctx context.Context, userID string) ([]*UserAPIKey, error) {
-	query := `
-		SELECT id, user_id, name, key_prefix, key_hash, permissions,
-		       is_active, expires_at, created_at, last_used_at,
-		       request_count_total, request_count_window, request_count_window_start
-		FROM api_keys
-		WHERE user_id = $1
-		ORDER BY created_at DESC
-	`
-
-	rows, err := s.db.Query(ctx, query, userID)
-	if err != nil {
-		return nil, fmt.Errorf("failed to list API keys: %w", err)
-	}
-	defer rows.Close()
-
-	keys := make([]*UserAPIKey, 0)
-	for rows.Next() {
-		key, err := s.scanAPIKey(rows)
-		if err != nil {
-			return nil, err
-		}
-		if key == nil {
-			continue
-		}
-		keys = append(keys, key)
-	}
-
-	return keys, rows.Err()
-}
-
-// UpdateAPIKey updates an API key.
-func (s *PostgresStore) UpdateAPIKey(ctx context.Context, key *UserAPIKey) error {
-	// Marshal permissions to JSONB
-	permissionsJSON, err := json.Marshal(key.Permissions)
-	if err != nil {
-		return fmt.Errorf("failed to marshal permissions: %w", err)
-	}
-
-	query := `
-		UPDATE api_keys SET
-			name = $2,
-			permissions = $3,
-			is_active = $4,
-			expires_at = $5,
-			last_used_at = $6
-		WHERE id = $1
-	`
-
-	result, err := s.db.Exec(ctx, query,
-		key.ID,
-		key.Name,
-		permissionsJSON,
-		key.IsActive,
-		key.ExpiresAt,
-		key.LastUsedAt,
-	)
-
-	if err != nil {
-		return fmt.Errorf("failed to update API key: %w", err)
-	}
-
-	if result.RowsAffected() == 0 {
-		return fmt.Errorf("API key not found: %s", key.ID)
-	}
-
-	return nil
-}
-
-// UpdateAPIKeyLastUsed atomically updates the last_used_at timestamp for an
-// API key. Retained for backwards compatibility with callers that only need
-// the timestamp update -- production code routes through RecordAPIKeyUsage,
-// which additionally maintains the usage counters from migration 000093.
-func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error {
-	query := `UPDATE api_keys SET last_used_at = NOW() WHERE id = $1`
-	result, err := s.db.Exec(ctx, query, keyID)
-	if err != nil {
-		return fmt.Errorf("failed to update API key last used: %w", err)
-	}
-	if result.RowsAffected() == 0 {
-		return fmt.Errorf("API key not found: %s", keyID)
-	}
-	return nil
-}
-
-// RecordAPIKeyUsage atomically updates last_used_at, adds delta to
-// request_count_total, and adds-or-resets request_count_window based on
-// whether the current window is still within apiKeyUsageWindow of its start.
-//
-// delta is the number of requests being recorded in this flush. The auth hot
-// path coalesces concurrent requests for the same key into a single write
-// (see Service.recordUsageAsync), so delta is frequently greater than 1 and
-// must be added rather than treated as a single increment.
-//
-// request_count_window is a FIXED/TUMBLING window counter, not a true
-// trailing-24h rolling count: the single UPDATE does the window decision
-// inline --
-//   - if window_start IS NULL OR (NOW() - window_start) >= apiKeyUsageWindow,
-//     start a fresh window (window_start = NOW(), count = delta) -- this
-//     DISCARDS whatever count the previous window had, even if some of those
-//     requests happened within the preceding window-length of NOW().
-//   - otherwise add delta to the existing count.
-//
-// The window length is passed in from apiKeyUsageWindow rather than written
-// as a SQL literal so the write path and the API read path (which zeroes an
-// expired window, see effectiveWindowUsage) cannot drift apart.
-//
-// An idle key's stale count lingers on the row unchanged until its next
-// request; the read path is responsible for not reporting it. Callers that
-// need the actual period covered should read request_count_window_start
-// rather than assuming "requests in the last 24h".
-//
-// Doing it in one statement keeps the update atomic per row, so two
-// concurrent calls can't both see "stale window" and reset in parallel --
-// pgx serializes updates to the same row.
-func (s *PostgresStore) RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error {
-	if delta <= 0 {
-		return fmt.Errorf("invalid API key usage delta %d: must be positive", delta)
-	}
-	query := `
-		UPDATE api_keys
-		SET last_used_at = NOW(),
-		    request_count_total = request_count_total + $2,
-		    request_count_window = CASE
-		        WHEN request_count_window_start IS NULL
-		             OR NOW() - request_count_window_start >= make_interval(secs => $3)
-		        THEN $2
-		        ELSE request_count_window + $2
-		    END,
-		    request_count_window_start = CASE
-		        WHEN request_count_window_start IS NULL
-		             OR NOW() - request_count_window_start >= make_interval(secs => $3)
-		        THEN NOW()
-		        ELSE request_count_window_start
-		    END
-		WHERE id = $1
-	`
-	result, err := s.db.Exec(ctx, query, keyID, delta, apiKeyUsageWindow.Seconds())
-	if err != nil {
-		return fmt.Errorf("failed to record API key usage: %w", err)
-	}
-	if result.RowsAffected() == 0 {
-		return fmt.Errorf("API key not found: %s", keyID)
-	}
-	return nil
-}
-
-// DeleteAPIKey deletes an API key.
-func (s *PostgresStore) DeleteAPIKey(ctx context.Context, keyID string) error {
-	query := `DELETE FROM api_keys WHERE id = $1`
-
-	result, err := s.db.Exec(ctx, query, keyID)
-	if err != nil {
-		return fmt.Errorf("failed to delete API key: %w", err)
-	}
-
-	if result.RowsAffected() == 0 {
-		return fmt.Errorf("API key not found: %s", keyID)
-	}
-
-	return nil
-}
-
 // ==========================================
 // HELPER FUNCTIONS
 // ==========================================
@@ -1088,56 +850,6 @@ func (s *PostgresStore) scanGroup(scanner Scanner) (*Group, error) {
 	return &group, nil
 }
 
-// scanAPIKey scans an API key from a database row.
-func (s *PostgresStore) scanAPIKey(scanner Scanner) (*UserAPIKey, error) {
-	var key UserAPIKey
-	var permissionsJSON []byte
-	var expiresAt, lastUsedAt, windowStart sql.NullTime
-
-	err := scanner.Scan(
-		&key.ID,
-		&key.UserID,
-		&key.Name,
-		&key.KeyPrefix,
-		&key.KeyHash,
-		&permissionsJSON,
-		&key.IsActive,
-		&expiresAt,
-		&key.CreatedAt,
-		&lastUsedAt,
-		&key.RequestCountTotal,
-		&key.RequestCountWindow,
-		&windowStart,
-	)
-
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, pgx.ErrNoRows
-		}
-		return nil, fmt.Errorf("failed to scan API key: %w", err)
-	}
-
-	// Unmarshal permissions
-	if len(permissionsJSON) > 0 {
-		if err := json.Unmarshal(permissionsJSON, &key.Permissions); err != nil {
-			return nil, fmt.Errorf("failed to unmarshal permissions: %w", err)
-		}
-	}
-
-	// Handle nullable timestamps
-	if expiresAt.Valid {
-		key.ExpiresAt = &expiresAt.Time
-	}
-	if lastUsedAt.Valid {
-		key.LastUsedAt = &lastUsedAt.Time
-	}
-	if windowStart.Valid {
-		key.RequestCountWindowStart = &windowStart.Time
-	}
-
-	return &key, nil
-}
-
 // Ping checks the database connection health.
 func (s *PostgresStore) Ping(ctx context.Context) error {
 	return s.db.Ping(ctx)
diff --git a/internal/auth/store_postgres_apikeys.go b/internal/auth/store_postgres_apikeys.go
new file mode 100644
index 000000000..2ca201606
--- /dev/null
+++ b/internal/auth/store_postgres_apikeys.go
@@ -0,0 +1,305 @@
+// PostgresStore's API-key surface, split out of store_postgres.go so that
+// file stops growing past the project's 500-line ceiling (CodeRabbit finding
+// on PR #1523). Pure move: the queries and scanning behavior are unchanged.
+
+package auth
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// ==========================================
+// API KEY OPERATIONS
+// ==========================================
+
+// CreateAPIKey creates a new API key.
+func (s *PostgresStore) CreateAPIKey(ctx context.Context, key *UserAPIKey) error {
+	// Generate UUID if not provided
+	if key.ID == "" {
+		key.ID = uuid.New().String()
+	}
+
+	// Set timestamps
+	key.CreatedAt = time.Now()
+
+	// Marshal permissions to JSONB
+	permissionsJSON, err := json.Marshal(key.Permissions)
+	if err != nil {
+		return fmt.Errorf("failed to marshal permissions: %w", err)
+	}
+
+	query := `
+		INSERT INTO api_keys (
+			id, user_id, name, key_prefix, key_hash, permissions,
+			is_active, expires_at, created_at, last_used_at
+		) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+	`
+
+	_, err = s.db.Exec(ctx, query,
+		key.ID,
+		key.UserID,
+		key.Name,
+		key.KeyPrefix,
+		key.KeyHash,
+		permissionsJSON,
+		key.IsActive,
+		key.ExpiresAt,
+		key.CreatedAt,
+		key.LastUsedAt,
+	)
+
+	if err != nil {
+		return fmt.Errorf("failed to create API key: %w", err)
+	}
+
+	return nil
+}
+
+// GetAPIKeyByID retrieves an API key by ID.
+func (s *PostgresStore) GetAPIKeyByID(ctx context.Context, keyID string) (*UserAPIKey, error) {
+	query := `
+		SELECT id, user_id, name, key_prefix, key_hash, permissions,
+		       is_active, expires_at, created_at, last_used_at,
+		       request_count_total, request_count_window, request_count_window_start
+		FROM api_keys
+		WHERE id = $1
+	`
+
+	return s.scanAPIKey(s.db.QueryRow(ctx, query, keyID))
+}
+
+// GetAPIKeyByHash retrieves an API key by hash.
+func (s *PostgresStore) GetAPIKeyByHash(ctx context.Context, keyHash string) (*UserAPIKey, error) {
+	query := `
+		SELECT id, user_id, name, key_prefix, key_hash, permissions,
+		       is_active, expires_at, created_at, last_used_at,
+		       request_count_total, request_count_window, request_count_window_start
+		FROM api_keys
+		WHERE key_hash = $1 AND is_active = true
+		  AND (expires_at IS NULL OR expires_at > NOW())
+	`
+
+	return s.scanAPIKey(s.db.QueryRow(ctx, query, keyHash))
+}
+
+// ListAPIKeysByUser lists all API keys for a user.
+func (s *PostgresStore) ListAPIKeysByUser(ctx context.Context, userID string) ([]*UserAPIKey, error) {
+	query := `
+		SELECT id, user_id, name, key_prefix, key_hash, permissions,
+		       is_active, expires_at, created_at, last_used_at,
+		       request_count_total, request_count_window, request_count_window_start
+		FROM api_keys
+		WHERE user_id = $1
+		ORDER BY created_at DESC
+	`
+
+	rows, err := s.db.Query(ctx, query, userID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list API keys: %w", err)
+	}
+	defer rows.Close()
+
+	keys := make([]*UserAPIKey, 0)
+	for rows.Next() {
+		key, err := s.scanAPIKey(rows)
+		if err != nil {
+			return nil, err
+		}
+		if key == nil {
+			continue
+		}
+		keys = append(keys, key)
+	}
+
+	return keys, rows.Err()
+}
+
+// UpdateAPIKey updates an API key.
+func (s *PostgresStore) UpdateAPIKey(ctx context.Context, key *UserAPIKey) error {
+	// Marshal permissions to JSONB
+	permissionsJSON, err := json.Marshal(key.Permissions)
+	if err != nil {
+		return fmt.Errorf("failed to marshal permissions: %w", err)
+	}
+
+	query := `
+		UPDATE api_keys SET
+			name = $2,
+			permissions = $3,
+			is_active = $4,
+			expires_at = $5,
+			last_used_at = $6
+		WHERE id = $1
+	`
+
+	result, err := s.db.Exec(ctx, query,
+		key.ID,
+		key.Name,
+		permissionsJSON,
+		key.IsActive,
+		key.ExpiresAt,
+		key.LastUsedAt,
+	)
+
+	if err != nil {
+		return fmt.Errorf("failed to update API key: %w", err)
+	}
+
+	if result.RowsAffected() == 0 {
+		return fmt.Errorf("API key not found: %s", key.ID)
+	}
+
+	return nil
+}
+
+// UpdateAPIKeyLastUsed atomically updates the last_used_at timestamp for an
+// API key. Retained for backwards compatibility with callers that only need
+// the timestamp update -- production code routes through RecordAPIKeyUsage,
+// which additionally maintains the usage counters from migration 000093.
+func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error {
+	query := `UPDATE api_keys SET last_used_at = NOW() WHERE id = $1`
+	result, err := s.db.Exec(ctx, query, keyID)
+	if err != nil {
+		return fmt.Errorf("failed to update API key last used: %w", err)
+	}
+	if result.RowsAffected() == 0 {
+		return fmt.Errorf("API key not found: %s", keyID)
+	}
+	return nil
+}
+
+// RecordAPIKeyUsage atomically updates last_used_at, adds delta to
+// request_count_total, and adds-or-resets request_count_window based on
+// whether the current window is still within apiKeyUsageWindow of its start.
+//
+// delta is the number of requests being recorded in this flush. The auth hot
+// path coalesces concurrent requests for the same key into a single write
+// (see Service.recordUsageAsync), so delta is frequently greater than 1 and
+// must be added rather than treated as a single increment.
+//
+// request_count_window is a FIXED/TUMBLING window counter, not a true
+// trailing-24h rolling count: the single UPDATE does the window decision
+// inline --
+//   - if window_start IS NULL OR (NOW() - window_start) >= apiKeyUsageWindow,
+//     start a fresh window (window_start = NOW(), count = delta) -- this
+//     DISCARDS whatever count the previous window had, even if some of those
+//     requests happened within the preceding window-length of NOW().
+//   - otherwise add delta to the existing count.
+//
+// The window length is passed in from apiKeyUsageWindow rather than written
+// as a SQL literal so the write path and the API read path (which zeroes an
+// expired window, see effectiveWindowUsage) cannot drift apart.
+//
+// An idle key's stale count lingers on the row unchanged until its next
+// request; the read path is responsible for not reporting it. Callers that
+// need the actual period covered should read request_count_window_start
+// rather than assuming "requests in the last 24h".
+//
+// Doing it in one statement keeps the update atomic per row, so two
+// concurrent calls can't both see "stale window" and reset in parallel --
+// pgx serializes updates to the same row.
+func (s *PostgresStore) RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error {
+	if delta <= 0 {
+		return fmt.Errorf("invalid API key usage delta %d: must be positive", delta)
+	}
+	query := `
+		UPDATE api_keys
+		SET last_used_at = NOW(),
+		    request_count_total = request_count_total + $2,
+		    request_count_window = CASE
+		        WHEN request_count_window_start IS NULL
+		             OR NOW() - request_count_window_start >= make_interval(secs => $3)
+		        THEN $2
+		        ELSE request_count_window + $2
+		    END,
+		    request_count_window_start = CASE
+		        WHEN request_count_window_start IS NULL
+		             OR NOW() - request_count_window_start >= make_interval(secs => $3)
+		        THEN NOW()
+		        ELSE request_count_window_start
+		    END
+		WHERE id = $1
+	`
+	result, err := s.db.Exec(ctx, query, keyID, delta, apiKeyUsageWindow.Seconds())
+	if err != nil {
+		return fmt.Errorf("failed to record API key usage: %w", err)
+	}
+	if result.RowsAffected() == 0 {
+		return fmt.Errorf("API key not found: %s", keyID)
+	}
+	return nil
+}
+
+// DeleteAPIKey deletes an API key.
+func (s *PostgresStore) DeleteAPIKey(ctx context.Context, keyID string) error {
+	query := `DELETE FROM api_keys WHERE id = $1`
+
+	result, err := s.db.Exec(ctx, query, keyID)
+	if err != nil {
+		return fmt.Errorf("failed to delete API key: %w", err)
+	}
+
+	if result.RowsAffected() == 0 {
+		return fmt.Errorf("API key not found: %s", keyID)
+	}
+
+	return nil
+}
+
+// scanAPIKey scans an API key from a database row.
+func (s *PostgresStore) scanAPIKey(scanner Scanner) (*UserAPIKey, error) {
+	var key UserAPIKey
+	var permissionsJSON []byte
+	var expiresAt, lastUsedAt, windowStart sql.NullTime
+
+	err := scanner.Scan(
+		&key.ID,
+		&key.UserID,
+		&key.Name,
+		&key.KeyPrefix,
+		&key.KeyHash,
+		&permissionsJSON,
+		&key.IsActive,
+		&expiresAt,
+		&key.CreatedAt,
+		&lastUsedAt,
+		&key.RequestCountTotal,
+		&key.RequestCountWindow,
+		&windowStart,
+	)
+
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, pgx.ErrNoRows
+		}
+		return nil, fmt.Errorf("failed to scan API key: %w", err)
+	}
+
+	// Unmarshal permissions
+	if len(permissionsJSON) > 0 {
+		if err := json.Unmarshal(permissionsJSON, &key.Permissions); err != nil {
+			return nil, fmt.Errorf("failed to unmarshal permissions: %w", err)
+		}
+	}
+
+	// Handle nullable timestamps
+	if expiresAt.Valid {
+		key.ExpiresAt = &expiresAt.Time
+	}
+	if lastUsedAt.Valid {
+		key.LastUsedAt = &lastUsedAt.Time
+	}
+	if windowStart.Valid {
+		key.RequestCountWindowStart = &windowStart.Time
+	}
+
+	return &key, nil
+}

From dcb2475d5290cf1886cd343806a6deeb0c1814af Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 19:59:39 +0200
Subject: [PATCH 5/8] fix(auth,frontend): report unmeasured lifetime counts as
 unknown, not 0

Migration 000093 added request_count_total with DEFAULT 0 and no backfill,
so every API key that already existed reads as zero regardless of how much
traffic it actually served. The UI presented that as "Requests (total): 0",
stating a request volume nobody measured, and the summary card folded those
fabricated zeros into an exact-looking lifetime sum.

RecordAPIKeyUsage is the only writer of last_used_at on the request path
and it always bumps the counter in the same statement, so "used at least
once yet carrying a zero lifetime count" identifies exactly the rows that
predate the counter. Those now report null, and the table renders "n/a"
instead of a number. A key that has genuinely never been used still
reports 0.

The section summary excludes unknown keys from total_requests_lifetime and
sets lifetime_partial, which the card renders as a "+" suffix so the total
reads as a lower bound rather than an exact figure.

The invariant this relies on is documented on effectiveLifetimeUsage: a new
caller of the legacy UpdateAPIKeyLastUsed, which bumps only the timestamp,
would break it. It currently has no production callers.
---
 frontend/src/__tests__/apikeys-usage.test.ts | 18 ++++
 frontend/src/__tests__/apikeys.test.ts       | 44 +++++++++-
 frontend/src/api/types.ts                    |  9 +-
 frontend/src/apikeys.ts                      | 20 +++--
 frontend/src/apikeys_usage.ts                | 11 ++-
 frontend/src/types.ts                        |  4 +-
 internal/api/openapi.yaml                    | 18 +++-
 internal/auth/service_apikeys_api.go         | 50 +++++++++--
 internal/auth/service_apikeys_api_test.go    | 90 +++++++++++++++++++-
 9 files changed, 246 insertions(+), 18 deletions(-)

diff --git a/frontend/src/__tests__/apikeys-usage.test.ts b/frontend/src/__tests__/apikeys-usage.test.ts
index 2d6c640aa..c6ff86d10 100644
--- a/frontend/src/__tests__/apikeys-usage.test.ts
+++ b/frontend/src/__tests__/apikeys-usage.test.ts
@@ -43,6 +43,24 @@ describe('renderApiKeysUsageSummary', () => {
     expect(tileValues(container)).toEqual(['2', '42', '1.2k']);
   });
 
+  // Regression: a lifetime total that excludes keys predating the counters is
+  // a lower bound. Rendering it bare would present an undercount as exact.
+  test('marks a partial lifetime total as a lower bound', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(stats({ lifetime_partial: true }));
+
+    expect(tileValues(container)[2]).toBe('1.2k+');
+  });
+
+  test('leaves a complete lifetime total unqualified', () => {
+    const container = setupContainer();
+
+    renderApiKeysUsageSummary(stats({ lifetime_partial: false }));
+
+    expect(tileValues(container)[2]).toBe('1.2k');
+  });
+
   test('renders the top-keys list when keys have window activity', () => {
     const container = setupContainer();
 
diff --git a/frontend/src/__tests__/apikeys.test.ts b/frontend/src/__tests__/apikeys.test.ts
index 4966289d8..2d74e8d71 100644
--- a/frontend/src/__tests__/apikeys.test.ts
+++ b/frontend/src/__tests__/apikeys.test.ts
@@ -1104,7 +1104,7 @@ describe('API Keys Module', () => {
       expect(container?.innerHTML).toContain('apikeys-count-cell');
     });
 
-    test('falls back to 0 when counter fields are missing from the response', async () => {
+    test('shows no data when counter fields are missing from the response', async () => {
       (api.getApiKeys as jest.Mock).mockResolvedValue({
         api_keys: [
           // No request_count_* fields — simulates a cached older response.
@@ -1117,8 +1117,48 @@ describe('API Keys Module', () => {
       const container = document.getElementById('apikeys-list');
       const cells = container?.querySelectorAll('.apikeys-count-cell');
       expect(cells?.length).toBe(2);
+      expect(cells?.[0]?.textContent).toBe('n/a');
+      expect(cells?.[1]?.textContent).toBe('n/a');
+    });
+
+    // Regression: a key already in use before migration 000093 has no
+    // recoverable lifetime count. The backend sends null for it; rendering
+    // "0" would state a request volume nobody measured. A genuinely-unused
+    // key still shows 0.
+    test('renders an unknown lifetime count as no data, and a real zero as 0', async () => {
+      (api.getApiKeys as jest.Mock).mockResolvedValue({
+        api_keys: [
+          {
+            id: 'pre-migration',
+            name: 'old',
+            key_prefix: 'abc12345',
+            is_active: true,
+            created_at: '2024-01-15T10:00:00Z',
+            request_count_window: 0,
+            request_count_total: null,
+          },
+          {
+            id: 'never-used',
+            name: 'fresh',
+            key_prefix: 'def67890',
+            is_active: true,
+            created_at: '2024-01-15T10:00:00Z',
+            request_count_window: 0,
+            request_count_total: 0,
+          },
+        ],
+      });
+
+      await loadApiKeys();
+
+      const cells = document.getElementById('apikeys-list')?.querySelectorAll('.apikeys-count-cell');
+      expect(cells?.length).toBe(4);
+      // Row 1: window 0 is a real value, lifetime is unknown.
       expect(cells?.[0]?.textContent).toBe('0');
-      expect(cells?.[1]?.textContent).toBe('0');
+      expect(cells?.[1]?.textContent).toBe('n/a');
+      // Row 2: never used, so both are a genuine zero.
+      expect(cells?.[2]?.textContent).toBe('0');
+      expect(cells?.[3]?.textContent).toBe('0');
     });
 
     test('list-fetch failure clears summary skeleton and shows error', async () => {
diff --git a/frontend/src/api/types.ts b/frontend/src/api/types.ts
index bd5b139fe..81efab6bb 100644
--- a/frontend/src/api/types.ts
+++ b/frontend/src/api/types.ts
@@ -584,7 +584,10 @@ export interface APIKeyInfo {
   // both come back as 0 / absent once that window has closed, so a key
   // that went idle reads as no current activity rather than replaying a
   // count from an old window.
-  request_count_total?: number;
+  // null when the key was already in use before migration 000093 added the
+  // counters, so its true lifetime volume is unrecoverable. Render it as
+  // "no data", never as 0.
+  request_count_total?: number | null;
   request_count_window?: number;
   request_count_window_start?: string;
 }
@@ -603,7 +606,11 @@ export interface APIKeysUsageStats {
   // Sum of each key's fixed-window counter across still-open windows --
   // not a true rolling 24h total, and the windows are not aligned.
   total_requests_window: number;
+  // Sums only the keys whose lifetime count is known. When lifetime_partial
+  // is true at least one key predates the counters, so this is a lower bound
+  // and must not be presented as an exact figure.
   total_requests_lifetime: number;
+  lifetime_partial?: boolean;
   top_keys: APIKeysUsageStatsTopKey[];
 }
 
diff --git a/frontend/src/apikeys.ts b/frontend/src/apikeys.ts
index 622692839..87962e849 100644
--- a/frontend/src/apikeys.ts
+++ b/frontend/src/apikeys.ts
@@ -14,6 +14,14 @@ import { showSkeletonRows, teardownSkeleton } from './lib/skeleton';
 // State for modal management
 let currentApiKeys: APIKeyInfo[] = [];
 
+/**
+ * Cell content for a request count the backend cannot report, i.e. a key
+ * already in use before migration 000093 introduced the counters. Static
+ * markup with no interpolated data, matching the "Never" treatment the
+ * Last Used and Expires columns already use for absent values.
+ */
+const NO_COUNT_DATA = '<span class="text-muted" title="Not recorded for this key">n/a</span>';
+
 /**
  * Load and display API keys.
  *
@@ -440,11 +448,13 @@ function showError(message: string): void {
  * uses a separate `formatCount` that abbreviates large values to fit
  * the tile width.
  *
- * Defends against missing fields (older cached responses without the
- * counters from migration 000093) and non-finite inputs by coercing
- * to 0 — never returns "undefined" or "NaN" to the rendered table.
+ * `null` means the backend does not know the count (a key already in use
+ * before migration 000093 added the counters) and renders as an em dash
+ * rather than "0", which would state a request volume nobody measured.
+ * `undefined` (an older cached response with no counter fields at all) is
+ * treated the same way, as is any non-finite or negative value.
  */
-function formatRequestCount(n: number | undefined): string {
-  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return '0';
+function formatRequestCount(n: number | null | undefined): string {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return NO_COUNT_DATA;
   return Math.trunc(n).toLocaleString('en-US');
 }
diff --git a/frontend/src/apikeys_usage.ts b/frontend/src/apikeys_usage.ts
index 56c54b3ed..8d5490b9e 100644
--- a/frontend/src/apikeys_usage.ts
+++ b/frontend/src/apikeys_usage.ts
@@ -68,7 +68,16 @@ export function renderApiKeysUsageSummary(stats: APIKeysUsageStats): void {
   tiles.className = 'apikeys-usage-tiles';
   tiles.appendChild(buildSummaryTile('Active keys', String(stats.total_active)));
   tiles.appendChild(buildSummaryTile('Requests (window)', formatCount(stats.total_requests_window)));
-  tiles.appendChild(buildSummaryTile('Requests (lifetime)', formatCount(stats.total_requests_lifetime)));
+  // A "+" suffix marks the lifetime total as a lower bound: at least one key
+  // was in use before the counters existed, so its share is unrecoverable and
+  // showing the sum unqualified would present an undercount as exact.
+  const lifetime = formatCount(stats.total_requests_lifetime);
+  tiles.appendChild(
+    buildSummaryTile(
+      'Requests (lifetime)',
+      stats.lifetime_partial ? `${lifetime}+` : lifetime
+    )
+  );
   card.appendChild(tiles);
 
   if (stats.top_keys && stats.top_keys.length > 0) {
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 69517dc87..f6a05c5e8 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -414,7 +414,9 @@ export interface APIKeyInfo {
   // a true rolling 24h total -- request_count_window_start says exactly
   // which period it covers, and both come back as 0 / absent once that
   // window has closed.
-  request_count_total?: number;
+  // null when the key predates migration 000093, i.e. the lifetime volume is
+  // unknown rather than zero.
+  request_count_total?: number | null;
   request_count_window?: number;
   request_count_window_start?: string;
 }
diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index ed00e3541..28f816258 100644
--- a/internal/api/openapi.yaml
+++ b/internal/api/openapi.yaml
@@ -2285,7 +2285,13 @@ components:
         request_count_total:
           type: integer
           format: int64
-          description: Lifetime request count since the key was created.
+          nullable: true
+          description: |
+            Lifetime request count since the key was created. Null when the
+            count is unknown: keys already in use before migration 000093
+            introduced the counter have no recoverable lifetime figure, and
+            reporting 0 for them would assert a volume nobody measured. A key
+            that has genuinely never been used reports 0, not null.
         request_count_window:
           type: integer
           format: int64
@@ -2332,7 +2338,15 @@ components:
         total_requests_lifetime:
           type: integer
           format: int64
-          description: Sum of request_count_total across the caller's keys.
+          description: |
+            Sum of request_count_total across the caller's keys, counting only
+            the keys whose lifetime count is known. See lifetime_partial.
+        lifetime_partial:
+          type: boolean
+          description: |
+            True when at least one key was excluded from total_requests_lifetime
+            because its usage predates the counters, making that total a lower
+            bound rather than an exact figure.
         top_keys:
           type: array
           description: |
diff --git a/internal/auth/service_apikeys_api.go b/internal/auth/service_apikeys_api.go
index a0cd31183..47d34d055 100644
--- a/internal/auth/service_apikeys_api.go
+++ b/internal/auth/service_apikeys_api.go
@@ -50,6 +50,28 @@ func effectiveWindowUsage(key *UserAPIKey, now time.Time) (int64, *time.Time) {
 	return key.RequestCountWindow, key.RequestCountWindowStart
 }
 
+// effectiveLifetimeUsage returns the lifetime request count to report, or nil
+// when the true count is not known.
+//
+// Migration 000093 added request_count_total with DEFAULT 0, so every key that
+// already existed reads as zero no matter how much traffic it actually served.
+// RecordAPIKeyUsage is the only writer of last_used_at on the request path and
+// it always bumps the counter in the same statement, so "has been used at
+// least once, yet carries a zero lifetime count" can only mean the usage
+// predates the counter. Reporting that as 0 would assert a request volume we
+// do not have; nil says "unknown" and lets the UI show it as such.
+//
+// This relies on last_used_at and request_count_total moving together. Any new
+// caller of the legacy UpdateAPIKeyLastUsed (which bumps only the timestamp)
+// would break the invariant and make a genuinely-unused key look unknown.
+func effectiveLifetimeUsage(key *UserAPIKey) *int64 {
+	if key.RequestCountTotal == 0 && key.LastUsedAt != nil {
+		return nil
+	}
+	total := key.RequestCountTotal
+	return &total
+}
+
 // API wrapper methods for API key operations
 // These methods return API-friendly types and handle type conversions
 
@@ -80,8 +102,14 @@ type APIKeyInfo struct {
 	// is a fixed/tumbling window count, not a true rolling 24h total, and is
 	// zero once that window has closed -- see effectiveWindowUsage,
 	// PostgresStore.RecordAPIKeyUsage and RequestCountWindowStart above.
-	RequestCountTotal  int64 `json:"request_count_total"`
-	RequestCountWindow int64 `json:"request_count_window"`
+	//
+	// RequestCountTotal is a pointer because "unknown" and "zero" are
+	// different answers: a key that was already in use before migration 000093
+	// added the counter has no recoverable lifetime figure, and reporting 0
+	// for it would be a fabricated number. nil means unknown; see
+	// effectiveLifetimeUsage.
+	RequestCountTotal  *int64 `json:"request_count_total"`
+	RequestCountWindow int64  `json:"request_count_window"`
 }
 
 // APIKeysUsageStatsTopKey is one entry in the top-keys list returned by
@@ -105,10 +133,16 @@ type APIKeysUsageStatsTopKey struct {
 //
 // TotalActive counts the keys the authentication path would accept, so a
 // key that is unrevoked but past its expiry is not counted.
+//
+// TotalRequestsLifetime sums only the keys whose lifetime count is known.
+// LifetimePartial reports whether any key was left out because its usage
+// predates migration 000093 (see effectiveLifetimeUsage), so the UI can show
+// the total as a lower bound instead of presenting an undercount as exact.
 type APIKeysUsageStatsResponse struct {
 	TotalActive           int                       `json:"total_active"`
 	TotalRequestsWindow   int64                     `json:"total_requests_window"`
 	TotalRequestsLifetime int64                     `json:"total_requests_lifetime"`
+	LifetimePartial       bool                      `json:"lifetime_partial"`
 	TopKeys               []APIKeysUsageStatsTopKey `json:"top_keys"`
 }
 
@@ -170,7 +204,7 @@ func (s *Service) CreateAPIKeyAPI(ctx context.Context, userID string, req any) (
 			CreatedAt:               keyInfo.CreatedAt,
 			LastUsedAt:              keyInfo.LastUsedAt,
 			IsActive:                keyInfo.IsActive,
-			RequestCountTotal:       keyInfo.RequestCountTotal,
+			RequestCountTotal:       effectiveLifetimeUsage(keyInfo),
 			RequestCountWindow:      keyInfo.RequestCountWindow,
 			RequestCountWindowStart: keyInfo.RequestCountWindowStart,
 		},
@@ -200,7 +234,7 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 			CreatedAt:               key.CreatedAt,
 			LastUsedAt:              key.LastUsedAt,
 			IsActive:                key.IsActive,
-			RequestCountTotal:       key.RequestCountTotal,
+			RequestCountTotal:       effectiveLifetimeUsage(key),
 			RequestCountWindow:      windowCount,
 			RequestCountWindowStart: windowStart,
 		})
@@ -248,7 +282,13 @@ func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (a
 			resp.TotalActive++
 		}
 		resp.TotalRequestsWindow += windowCount
-		resp.TotalRequestsLifetime += k.RequestCountTotal
+		if lifetime := effectiveLifetimeUsage(k); lifetime != nil {
+			resp.TotalRequestsLifetime += *lifetime
+		} else {
+			// Pre-000093 key: its real lifetime count is unrecoverable, so
+			// the total is a lower bound rather than an exact figure.
+			resp.LifetimePartial = true
+		}
 		activity = append(activity, apiKeyActivity{key: k, window: windowCount})
 	}
 
diff --git a/internal/auth/service_apikeys_api_test.go b/internal/auth/service_apikeys_api_test.go
index b3c507b45..5f6504cc6 100644
--- a/internal/auth/service_apikeys_api_test.go
+++ b/internal/auth/service_apikeys_api_test.go
@@ -242,7 +242,8 @@ func TestService_ListUserAPIKeysAPI(t *testing.T) {
 		assert.Equal(t, int64(0), resp.APIKeys[0].RequestCountWindow)
 		assert.Nil(t, resp.APIKeys[0].RequestCountWindowStart)
 		// Lifetime is unaffected by the window expiring.
-		assert.Equal(t, int64(900), resp.APIKeys[0].RequestCountTotal)
+		require.NotNil(t, resp.APIKeys[0].RequestCountTotal)
+		assert.Equal(t, int64(900), *resp.APIKeys[0].RequestCountTotal)
 
 		// Live window passes through untouched.
 		assert.Equal(t, int64(11), resp.APIKeys[1].RequestCountWindow)
@@ -254,6 +255,44 @@ func TestService_ListUserAPIKeysAPI(t *testing.T) {
 		assert.Nil(t, resp.APIKeys[2].RequestCountWindowStart)
 	})
 
+	// Regression: migration 000093 added request_count_total with DEFAULT 0,
+	// so a key that was already serving traffic reads as zero. Reporting that
+	// as "0 requests" states a volume nobody measured. It must come back as
+	// unknown (nil) instead, while a genuinely-unused key still reports 0.
+	t.Run("reports an unmeasured lifetime count as unknown, not zero", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		usedAt := time.Now().Add(-1 * time.Hour)
+		keys := []*UserAPIKey{
+			// Used before the counters existed: zero here means "not recorded".
+			{ID: "pre-migration", LastUsedAt: &usedAt, RequestCountTotal: 0},
+			// Never used at all: zero is the true count.
+			{ID: "never-used", RequestCountTotal: 0},
+			// Counted normally.
+			{ID: "counted", LastUsedAt: &usedAt, RequestCountTotal: 12},
+		}
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.ListUserAPIKeysAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIListAPIKeysResponse)
+		require.True(t, ok)
+		require.Len(t, resp.APIKeys, 3)
+
+		assert.Nil(t, resp.APIKeys[0].RequestCountTotal, "pre-migration key must report unknown, not 0")
+
+		require.NotNil(t, resp.APIKeys[1].RequestCountTotal)
+		assert.Equal(t, int64(0), *resp.APIKeys[1].RequestCountTotal)
+
+		require.NotNil(t, resp.APIKeys[2].RequestCountTotal)
+		assert.Equal(t, int64(12), *resp.APIKeys[2].RequestCountTotal)
+	})
+
 	// #492: last_used_at must round-trip through ListUserAPIKeysAPI so the
 	// frontend can render "Last used" without a separate endpoint.
 	t.Run("last_used_at is present in response when key was used (issue #492)", func(t *testing.T) {
@@ -685,6 +724,55 @@ func TestService_GetAPIKeysUsageStatsAPI(t *testing.T) {
 		assert.Equal(t, 2, resp.TotalActive)
 	})
 
+	// Regression: an unmeasured key must not contribute a fabricated 0 to the
+	// lifetime total silently. It is excluded and the response says so, so the
+	// UI can show a lower bound instead of an exact-looking undercount.
+	t.Run("flags the lifetime total as partial when a key predates the counters", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		usedAt := time.Now().Add(-1 * time.Hour)
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		keys := []*UserAPIKey{
+			{ID: "pre-migration", IsActive: true, LastUsedAt: &usedAt, RequestCountTotal: 0},
+			{ID: "counted", IsActive: true, LastUsedAt: &usedAt, RequestCountTotal: 40},
+		}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		assert.Equal(t, int64(40), resp.TotalRequestsLifetime)
+		assert.True(t, resp.LifetimePartial)
+	})
+
+	t.Run("does not flag the total as partial when every key is measured", func(t *testing.T) {
+		mockStore := new(MockStore)
+		t.Cleanup(func() { mockStore.AssertExpectations(t) })
+		service := &Service{store: mockStore}
+
+		usedAt := time.Now().Add(-1 * time.Hour)
+		user := &User{ID: "user-123", Email: "test@example.com", Active: true}
+		keys := []*UserAPIKey{
+			{ID: "counted", IsActive: true, LastUsedAt: &usedAt, RequestCountTotal: 40},
+			{ID: "never-used", IsActive: true, RequestCountTotal: 0},
+		}
+		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
+		mockStore.On("ListAPIKeysByUser", ctx, "user-123").Return(keys, nil)
+
+		result, err := service.GetAPIKeysUsageStatsAPI(ctx, "user-123")
+		require.NoError(t, err)
+
+		resp, ok := result.(*APIKeysUsageStatsResponse)
+		require.True(t, ok)
+		assert.Equal(t, int64(40), resp.TotalRequestsLifetime)
+		assert.False(t, resp.LifetimePartial)
+	})
+
 	t.Run("returns empty stats when user has no keys", func(t *testing.T) {
 		mockStore := new(MockStore)
 		t.Cleanup(func() { mockStore.AssertExpectations(t) })

From 9a55d1927828cdcad3949e10523809080fb0ebf1 Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 20:10:43 +0200
Subject: [PATCH 6/8] fix(db): renumber API-key usage-counter migration 000093
 -> 000094

main gained 000093_recommendations_state_owner_id after this branch
claimed the number, so the merge ref carried two 000093 migrations and
CI's check-migration-conflicts hook failed. The collision is invisible
locally because each ref on its own is consistent.

Renamed via git mv and updated every reference to the number in the Go
doc comments, the OpenAPI descriptions, the frontend type comments and
the tests.

Verified against the merge ref (origin/main union this branch): no
migration number appears twice.
---
 frontend/src/__tests__/apikeys.test.ts                 |  2 +-
 frontend/src/api/types.ts                              |  4 ++--
 frontend/src/apikeys.ts                                |  4 ++--
 frontend/src/types.ts                                  |  4 ++--
 internal/api/openapi.yaml                              |  2 +-
 internal/auth/interfaces.go                            |  2 +-
 internal/auth/service_apikeys_api.go                   | 10 +++++-----
 internal/auth/service_apikeys_api_test.go              |  2 +-
 internal/auth/store_postgres_apikeys.go                |  2 +-
 internal/auth/types.go                                 |  2 +-
 ...own.sql => 000094_api_keys_usage_counters.down.sql} |  2 +-
 ...rs.up.sql => 000094_api_keys_usage_counters.up.sql} |  0
 12 files changed, 18 insertions(+), 18 deletions(-)
 rename internal/database/postgres/migrations/{000093_api_keys_usage_counters.down.sql => 000094_api_keys_usage_counters.down.sql} (78%)
 rename internal/database/postgres/migrations/{000093_api_keys_usage_counters.up.sql => 000094_api_keys_usage_counters.up.sql} (100%)

diff --git a/frontend/src/__tests__/apikeys.test.ts b/frontend/src/__tests__/apikeys.test.ts
index 2d74e8d71..96d853402 100644
--- a/frontend/src/__tests__/apikeys.test.ts
+++ b/frontend/src/__tests__/apikeys.test.ts
@@ -1121,7 +1121,7 @@ describe('API Keys Module', () => {
       expect(cells?.[1]?.textContent).toBe('n/a');
     });
 
-    // Regression: a key already in use before migration 000093 has no
+    // Regression: a key already in use before migration 000094 has no
     // recoverable lifetime count. The backend sends null for it; rendering
     // "0" would state a request volume nobody measured. A genuinely-unused
     // key still shows 0.
diff --git a/frontend/src/api/types.ts b/frontend/src/api/types.ts
index 81efab6bb..459bad021 100644
--- a/frontend/src/api/types.ts
+++ b/frontend/src/api/types.ts
@@ -578,13 +578,13 @@ export interface APIKeyInfo {
   // Usage counters (issue #340/#344 deferred sub-task).
   // Optional in the type so older mock data / cached responses without
   // the columns don't blow up the renderer -- but the backend always
-  // sends them as of migration 000093. request_count_window is a
+  // sends them as of migration 000094. request_count_window is a
   // FIXED/TUMBLING window count, not a true rolling 24h total --
   // request_count_window_start says exactly which period it covers, and
   // both come back as 0 / absent once that window has closed, so a key
   // that went idle reads as no current activity rather than replaying a
   // count from an old window.
-  // null when the key was already in use before migration 000093 added the
+  // null when the key was already in use before migration 000094 added the
   // counters, so its true lifetime volume is unrecoverable. Render it as
   // "no data", never as 0.
   request_count_total?: number | null;
diff --git a/frontend/src/apikeys.ts b/frontend/src/apikeys.ts
index 87962e849..3aae291f9 100644
--- a/frontend/src/apikeys.ts
+++ b/frontend/src/apikeys.ts
@@ -16,7 +16,7 @@ let currentApiKeys: APIKeyInfo[] = [];
 
 /**
  * Cell content for a request count the backend cannot report, i.e. a key
- * already in use before migration 000093 introduced the counters. Static
+ * already in use before migration 000094 introduced the counters. Static
  * markup with no interpolated data, matching the "Never" treatment the
  * Last Used and Expires columns already use for absent values.
  */
@@ -449,7 +449,7 @@ function showError(message: string): void {
  * the tile width.
  *
  * `null` means the backend does not know the count (a key already in use
- * before migration 000093 added the counters) and renders as an em dash
+ * before migration 000094 added the counters) and renders as an em dash
  * rather than "0", which would state a request volume nobody measured.
  * `undefined` (an older cached response with no counter fields at all) is
  * treated the same way, as is any non-finite or negative value.
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index f6a05c5e8..aeb9823fd 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -410,11 +410,11 @@ export interface APIKeyInfo {
   // Usage counters (issue #340/#344 deferred sub-task). Optional so
   // older mock data / cached responses without the columns don't blow
   // up the renderer -- the backend always sends them as of migration
-  // 000093. request_count_window is a FIXED/TUMBLING window count, not
+  // 000094. request_count_window is a FIXED/TUMBLING window count, not
   // a true rolling 24h total -- request_count_window_start says exactly
   // which period it covers, and both come back as 0 / absent once that
   // window has closed.
-  // null when the key predates migration 000093, i.e. the lifetime volume is
+  // null when the key predates migration 000094, i.e. the lifetime volume is
   // unknown rather than zero.
   request_count_total?: number | null;
   request_count_window?: number;
diff --git a/internal/api/openapi.yaml b/internal/api/openapi.yaml
index 28f816258..36809a380 100644
--- a/internal/api/openapi.yaml
+++ b/internal/api/openapi.yaml
@@ -2288,7 +2288,7 @@ components:
           nullable: true
           description: |
             Lifetime request count since the key was created. Null when the
-            count is unknown: keys already in use before migration 000093
+            count is unknown: keys already in use before migration 000094
             introduced the counter have no recoverable lifetime figure, and
             reporting 0 for them would assert a volume nobody measured. A key
             that has genuinely never been used reports 0, not null.
diff --git a/internal/auth/interfaces.go b/internal/auth/interfaces.go
index 5fc88a765..52fd60859 100644
--- a/internal/auth/interfaces.go
+++ b/internal/auth/interfaces.go
@@ -56,7 +56,7 @@ type StoreInterface interface {
 	// fixed/tumbling window count (not a true trailing-24h rolling count):
 	// it resets (along with request_count_window_start) when the existing
 	// window is older than apiKeyUsageWindow. Stale windows are zeroed on
-	// read, not on write -- see effectiveWindowUsage. See migration 000093
+	// read, not on write -- see effectiveWindowUsage. See migration 000094
 	// for the column shape.
 	RecordAPIKeyUsage(ctx context.Context, keyID string, delta int64) error
 	DeleteAPIKey(ctx context.Context, keyID string) error
diff --git a/internal/auth/service_apikeys_api.go b/internal/auth/service_apikeys_api.go
index 47d34d055..c1d9c6c40 100644
--- a/internal/auth/service_apikeys_api.go
+++ b/internal/auth/service_apikeys_api.go
@@ -53,7 +53,7 @@ func effectiveWindowUsage(key *UserAPIKey, now time.Time) (int64, *time.Time) {
 // effectiveLifetimeUsage returns the lifetime request count to report, or nil
 // when the true count is not known.
 //
-// Migration 000093 added request_count_total with DEFAULT 0, so every key that
+// Migration 000094 added request_count_total with DEFAULT 0, so every key that
 // already existed reads as zero no matter how much traffic it actually served.
 // RecordAPIKeyUsage is the only writer of last_used_at on the request path and
 // it always bumps the counter in the same statement, so "has been used at
@@ -104,7 +104,7 @@ type APIKeyInfo struct {
 	// PostgresStore.RecordAPIKeyUsage and RequestCountWindowStart above.
 	//
 	// RequestCountTotal is a pointer because "unknown" and "zero" are
-	// different answers: a key that was already in use before migration 000093
+	// different answers: a key that was already in use before migration 000094
 	// added the counter has no recoverable lifetime figure, and reporting 0
 	// for it would be a fabricated number. nil means unknown; see
 	// effectiveLifetimeUsage.
@@ -136,7 +136,7 @@ type APIKeysUsageStatsTopKey struct {
 //
 // TotalRequestsLifetime sums only the keys whose lifetime count is known.
 // LifetimePartial reports whether any key was left out because its usage
-// predates migration 000093 (see effectiveLifetimeUsage), so the UI can show
+// predates migration 000094 (see effectiveLifetimeUsage), so the UI can show
 // the total as a lower bound instead of presenting an undercount as exact.
 type APIKeysUsageStatsResponse struct {
 	TotalActive           int                       `json:"total_active"`
@@ -248,7 +248,7 @@ func (s *Service) ListUserAPIKeysAPI(ctx context.Context, userID string) (any, e
 // GetAPIKeysUsageStatsAPI computes section-level usage stats for the
 // calling user's own API keys. Aggregated in-process so we don't need a
 // separate DB round-trip -- ListUserAPIKeys already returns the per-key
-// counters from migration 000093.
+// counters from migration 000094.
 //
 // The "top keys" list is sorted by effective window count descending, with
 // total-lifetime as the tiebreaker so a long-running idle key doesn't
@@ -285,7 +285,7 @@ func (s *Service) GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (a
 		if lifetime := effectiveLifetimeUsage(k); lifetime != nil {
 			resp.TotalRequestsLifetime += *lifetime
 		} else {
-			// Pre-000093 key: its real lifetime count is unrecoverable, so
+			// Pre-000094 key: its real lifetime count is unrecoverable, so
 			// the total is a lower bound rather than an exact figure.
 			resp.LifetimePartial = true
 		}
diff --git a/internal/auth/service_apikeys_api_test.go b/internal/auth/service_apikeys_api_test.go
index 5f6504cc6..e1996d70a 100644
--- a/internal/auth/service_apikeys_api_test.go
+++ b/internal/auth/service_apikeys_api_test.go
@@ -255,7 +255,7 @@ func TestService_ListUserAPIKeysAPI(t *testing.T) {
 		assert.Nil(t, resp.APIKeys[2].RequestCountWindowStart)
 	})
 
-	// Regression: migration 000093 added request_count_total with DEFAULT 0,
+	// Regression: migration 000094 added request_count_total with DEFAULT 0,
 	// so a key that was already serving traffic reads as zero. Reporting that
 	// as "0 requests" states a volume nobody measured. It must come back as
 	// unknown (nil) instead, while a genuinely-unused key still reports 0.
diff --git a/internal/auth/store_postgres_apikeys.go b/internal/auth/store_postgres_apikeys.go
index 2ca201606..fe6c8c316 100644
--- a/internal/auth/store_postgres_apikeys.go
+++ b/internal/auth/store_postgres_apikeys.go
@@ -163,7 +163,7 @@ func (s *PostgresStore) UpdateAPIKey(ctx context.Context, key *UserAPIKey) error
 // UpdateAPIKeyLastUsed atomically updates the last_used_at timestamp for an
 // API key. Retained for backwards compatibility with callers that only need
 // the timestamp update -- production code routes through RecordAPIKeyUsage,
-// which additionally maintains the usage counters from migration 000093.
+// which additionally maintains the usage counters from migration 000094.
 func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string) error {
 	query := `UPDATE api_keys SET last_used_at = NOW() WHERE id = $1`
 	result, err := s.db.Exec(ctx, query, keyID)
diff --git a/internal/auth/types.go b/internal/auth/types.go
index f0554af0b..cab2240a1 100644
--- a/internal/auth/types.go
+++ b/internal/auth/types.go
@@ -78,7 +78,7 @@ type UserAPIKey struct {
 	KeyHash     string       `json:"-" dynamodbav:"KeyHash"`
 	Permissions []Permission `json:"permissions,omitempty" dynamodbav:"Permissions"`
 	IsActive    bool         `json:"is_active" dynamodbav:"IsActive"`
-	// Usage counters (issue #340/#344 deferred sub-task -- migration 000093).
+	// Usage counters (issue #340/#344 deferred sub-task -- migration 000094).
 	// Both default to 0 for legacy rows. RequestCountWindow is a
 	// FIXED/TUMBLING window count, not a true trailing-24h rolling count:
 	// the store's RecordAPIKeyUsage path restarts it (and
diff --git a/internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
similarity index 78%
rename from internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql
rename to internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
index b31a7f567..d3ab37400 100644
--- a/internal/database/postgres/migrations/000093_api_keys_usage_counters.down.sql
+++ b/internal/database/postgres/migrations/000094_api_keys_usage_counters.down.sql
@@ -1,4 +1,4 @@
--- Roll back API key usage counters (000093).
+-- Roll back API key usage counters (000094).
 ALTER TABLE api_keys
     DROP COLUMN IF EXISTS request_count_window_start,
     DROP COLUMN IF EXISTS request_count_window,
diff --git a/internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
similarity index 100%
rename from internal/database/postgres/migrations/000093_api_keys_usage_counters.up.sql
rename to internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql

From 12367e3e5a90253c227317df45e9f96fe7a8eb55 Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Mon, 27 Jul 2026 23:01:22 +0200
Subject: [PATCH 7/8] fix(auth,frontend,db): align usage-counter docs and test
 timeout with shipped semantics

Addresses the three actionable findings from the CodeRabbit pass on
e20ca1e. All three are accuracy defects introduced by earlier correct
fixes that did not carry their documentation along.

- frontend/src/api/apikeys.ts: the getApiKeysUsageStats doc comment still
  described top keys as ranked "by 24h activity", contradicting the
  rename of request_count_24h to request_count_window. The counter is a
  fixed/tumbling window, not a rolling 24h total, so the comment now
  names the field and its windowing semantics to match the wording
  already used on APIKeyInfo and APIKeysUsageStats.

- internal/auth/service_apikeys_test.go: raise the async
  RecordAPIKeyUsage deadline from 500ms to 5s, matching the two sibling
  tests that wait on the same kind of background write. 500ms is a real
  flake hazard on a loaded CI runner. The signalling channel and the
  t.Fatal on timeout are unchanged, so the test still fails if usage
  recording is dropped entirely.

- internal/database/postgres/migrations/000094: the comment claimed all
  existing rows display "0 requests". The read path no longer does that.
  effectiveLifetimeUsage treats a zero request_count_total on a key with
  a non-null last_used_at as unknown rather than zero, surfacing it as
  lifetime_partial, precisely so a pre-migration key is not reported as
  having served no traffic. The comment now describes that split and
  points at the function enforcing it.

Comment-only and test-only; no production behaviour changes.
---
 frontend/src/api/apikeys.ts                              | 3 ++-
 internal/auth/service_apikeys_test.go                    | 2 +-
 .../migrations/000094_api_keys_usage_counters.up.sql     | 9 +++++++--
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/frontend/src/api/apikeys.ts b/frontend/src/api/apikeys.ts
index b70901ae0..f95a1692b 100644
--- a/frontend/src/api/apikeys.ts
+++ b/frontend/src/api/apikeys.ts
@@ -20,7 +20,8 @@ export async function getApiKeys(): Promise<GetAPIKeysResponse> {
 /**
  * Get section-level API keys usage stats (issue #340/#344 deferred
  * sub-task). Returns the per-section summary card -- totals + top keys
- * by 24h activity. Scoped to the calling user's own keys.
+ * ranked by request_count_window, which is a FIXED/TUMBLING window count
+ * rather than a rolling 24h total. Scoped to the calling user's own keys.
  */
 export async function getApiKeysUsageStats(): Promise<APIKeysUsageStats> {
   return apiRequest<APIKeysUsageStats>('/api-keys/usage-stats');
diff --git a/internal/auth/service_apikeys_test.go b/internal/auth/service_apikeys_test.go
index 2024b2e9b..3efd22607 100644
--- a/internal/auth/service_apikeys_test.go
+++ b/internal/auth/service_apikeys_test.go
@@ -527,7 +527,7 @@ func TestService_ValidateUserAPIKey(t *testing.T) {
 		assert.Equal(t, apiKeyRecord, resultKey)
 		select {
 		case <-usageRecorded:
-		case <-time.After(500 * time.Millisecond):
+		case <-time.After(5 * time.Second):
 			t.Fatal("expected RecordAPIKeyUsage to be called")
 		}
 		mockStore.AssertExpectations(t)
diff --git a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
index 716a2a1a6..5de0e5f43 100644
--- a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
+++ b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
@@ -30,8 +30,13 @@
 --                                  see exactly which period the count
 --                                  covers instead of assuming "last 24h".
 --
--- Counters default to 0 so all existing rows show "0 requests" rather
--- than "(null)" in the UI. The window-start column is nullable because
+-- Counters default to 0 because the columns are NOT NULL. That default is
+-- not the same as "this key served no traffic": a key that was already in
+-- use before this migration also reads as 0. The read path distinguishes
+-- the two by last_used_at -- a zero request_count_total on a key that has
+-- been used is reported as unknown (nil, surfacing as lifetime_partial),
+-- while a never-used row keeps its genuine 0. See effectiveLifetimeUsage
+-- in service_apikeys_api.go. The window-start column is nullable because
 -- a row with zero-ever-usage shouldn't lie about when its window began.
 
 ALTER TABLE api_keys

From 18c46f39af1754adf07b632e41a7c0d8befd4f19 Mon Sep 17 00:00:00 2001
From: Cristian Magherusan-Stanciu <cristi.magherusan@gmail.com>
Date: Tue, 28 Jul 2026 21:29:39 +0200
Subject: [PATCH 8/8] fix(auth): book API key usage per request, not per
 validation

The usage counters added by this PR were incremented inside
auth.Service.ValidateUserAPIKey, i.e. once per CREDENTIAL VALIDATION.
A single HTTP request validates the same key several times over:
validateSecurityContext resolves the principal (1), then every
permission check re-validates it (1 more), and the multi-verb gates
re-validate once per verb. Reported volume was therefore 2x on a plain
gate and 5x on the four-verb planned-purchase gate: 100 requests were
reported as 200-400. The multiplier varies per endpoint, so the stored
totals cannot be corrected retroactively by dividing them down.

The multiplicity is pre-existing and was harmless while the async write
was an idempotent last_used_at timestamp. Turning it into an additive
counter converted it into a systematic overcount, made worse by the
singleflight accumulator, which correctly conserves the whole pending
delta and so preserves every surplus booking.

ValidateUserAPIKey is now a pure validation primitive with no usage
side effect, and usage is booked exactly once in
Handler.validateSecurityContext, the one code path guaranteed to run
once per inbound request. Principal carries the resolved API key ID so
the booking needs no second lookup, and principalFromUserAPIKey now
fails closed when validation yields no usable key record rather than
authenticating a key it cannot attribute usage to.

Regression coverage sits at the HandleRequest layer, where the defect
actually lives; a service-level test cannot see it, because it books
correctly when called once. internal/server drives a real
auth.Service behind a real api.Handler and asserts one store booking
per request on both the single-verb and four-verb paths. Both fail on
the pre-fix code (2 and 5 bookings respectively). internal/api adds
the handler-side half: which principal kinds book, how often, and
against which key ID.

Also addresses three CodeRabbit findings:
- formatRequestCount's doc claimed an em dash; NO_COUNT_DATA renders
  "n/a".
- Migration 000094 pointed at store_postgres.go; RecordAPIKeyUsage
  lives in store_postgres_apikeys.go.
- CreateAPIKeyAPI read the window counters raw while every other
  exposure site goes through effectiveWindowUsage. It cannot misreport
  today (keyInfo is built in memory and its counters are necessarily
  zero), but it now shares the one implementation so the invariant
  holds structurally.
---
 frontend/src/apikeys.ts                       |   5 +-
 internal/api/apikey_usage_booking_test.go     | 100 ++++++++
 internal/api/handler.go                       |  12 +
 internal/api/handler_ri_exchange_test.go      |   1 +
 internal/api/middleware.go                    |  29 ++-
 internal/api/mocks_test.go                    |  27 +++
 internal/api/router_authuser_test.go          |  10 +-
 internal/api/types.go                         |  11 +
 internal/auth/service.go                      |   2 +-
 internal/auth/service_apikeys.go              |  20 +-
 internal/auth/service_apikeys_api.go          |  13 +-
 internal/auth/service_apikeys_api_test.go     |   6 +-
 internal/auth/service_apikeys_test.go         |  72 +++---
 internal/auth/service_security_test.go        |  42 +---
 internal/auth/store_postgres_apikeys.go       |   2 +-
 .../000094_api_keys_usage_counters.up.sql     |   3 +-
 internal/server/apikey_usage_booking_test.go  | 220 ++++++++++++++++++
 internal/server/app.go                        |   4 +
 18 files changed, 483 insertions(+), 96 deletions(-)
 create mode 100644 internal/api/apikey_usage_booking_test.go
 create mode 100644 internal/server/apikey_usage_booking_test.go

diff --git a/frontend/src/apikeys.ts b/frontend/src/apikeys.ts
index 3aae291f9..065cd6e65 100644
--- a/frontend/src/apikeys.ts
+++ b/frontend/src/apikeys.ts
@@ -449,8 +449,9 @@ function showError(message: string): void {
  * the tile width.
  *
  * `null` means the backend does not know the count (a key already in use
- * before migration 000094 added the counters) and renders as an em dash
- * rather than "0", which would state a request volume nobody measured.
+ * before migration 000094 added the counters) and renders as NO_COUNT_DATA
+ * ("n/a") rather than "0", which would state a request volume nobody
+ * measured.
  * `undefined` (an older cached response with no counter fields at all) is
  * treated the same way, as is any non-finite or negative value.
  */
diff --git a/internal/api/apikey_usage_booking_test.go b/internal/api/apikey_usage_booking_test.go
new file mode 100644
index 000000000..a0e5f8de7
--- /dev/null
+++ b/internal/api/apikey_usage_booking_test.go
@@ -0,0 +1,100 @@
+package api //nolint:revive // var-naming: package name "api" is intentional for handler package
+
+import (
+	"context"
+	"testing"
+
+	"github.com/LeanerCloud/CUDly/internal/auth"
+	"github.com/aws/aws-lambda-go/events"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+// API key usage is booked in validateSecurityContext and nowhere else,
+// because that is the one code path guaranteed to run exactly once per
+// inbound request. These tests pin that contract at the api layer: which
+// principal kinds book, how many times, and against which key ID.
+//
+// They cannot on their own prove the per-validation overcount is gone --
+// MockAuthService stubs the validation and permission calls, so no real
+// booking path runs. The end-to-end guards in
+// internal/server/apikey_usage_booking_test.go cover that; these cover the
+// handler-side half of the contract cheaply and deterministically.
+
+func usageBookingLambdaRequest(headers map[string]string, method, path string) *events.LambdaFunctionURLRequest {
+	return &events.LambdaFunctionURLRequest{
+		Headers: headers,
+		RequestContext: events.LambdaFunctionURLRequestContext{
+			HTTP: events.LambdaFunctionURLRequestContextHTTPDescription{Method: method, Path: path},
+		},
+	}
+}
+
+// TestHandleRequest_UserAPIKeyBooksUsageOnceWithResolvedKeyID verifies that an
+// API-key-authenticated request books exactly one usage, against the key ID
+// the credential resolved to -- even though the request validates the
+// credential again inside the permission check.
+func TestHandleRequest_UserAPIKeyBooksUsageOnceWithResolvedKeyID(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+	t.Cleanup(func() { mockAuth.AssertExpectations(t) })
+
+	user := &auth.User{ID: "api-key-user", Email: "user@example.com"}
+	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").
+		Return(&auth.UserAPIKey{ID: "key-1"}, user, nil).Once()
+	mockAuth.On("HasAPIKeyPermissionAPI", mock.Anything, "user-key", "view", "api-keys").
+		Return("api-key-user", "key-1", true, nil).Once()
+	mockAuth.On("GetAPIKeysUsageStatsAPI", mock.Anything, "api-key-user").
+		Return(&auth.APIKeysUsageStatsResponse{}, nil).Once()
+
+	h := &Handler{auth: mockAuth}
+	resp, err := h.HandleRequest(ctx,
+		usageBookingLambdaRequest(map[string]string{"X-API-Key": "user-key"},
+			"GET", "/api/api-keys/usage-stats"))
+
+	require.NoError(t, err)
+	require.Equal(t, 200, resp.StatusCode, "body: %s", resp.Body)
+	require.Equal(t, []string{"key-1"}, mockAuth.UsageBookings(),
+		"one request must book exactly one usage, against the resolved key ID")
+}
+
+// TestHandleRequest_SessionAuthBooksNoAPIKeyUsage verifies that a
+// session-authenticated request books nothing: there is no key to attribute
+// it to, and booking would inflate whichever key happened to be nearby.
+func TestHandleRequest_SessionAuthBooksNoAPIKeyUsage(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+	t.Cleanup(func() { mockAuth.AssertExpectations(t) })
+
+	mockAuth.On("ValidateSession", ctx, "session-token").
+		Return(&Session{UserID: "session-user"}, nil).Once()
+	mockAuth.On("GetUserPermissionsAPI", mock.Anything, "session-user").
+		Return([]auth.APIPermission{}, nil).Once()
+
+	h := &Handler{auth: mockAuth}
+	resp, err := h.HandleRequest(ctx,
+		usageBookingLambdaRequest(map[string]string{"Authorization": "Bearer session-token"},
+			"GET", "/api/auth/me/permissions"))
+
+	require.NoError(t, err)
+	require.Equal(t, 200, resp.StatusCode, "body: %s", resp.Body)
+	require.Empty(t, mockAuth.UsageBookings(), "session auth must not book API key usage")
+}
+
+// TestHandleRequest_AdminAPIKeyBooksNoUsage verifies that the shared admin
+// API key books nothing. It is a stateless infrastructure credential with no
+// api_keys row, so there is no counter to increment.
+func TestHandleRequest_AdminAPIKeyBooksNoUsage(t *testing.T) {
+	ctx := context.Background()
+	mockAuth := new(MockAuthService)
+	t.Cleanup(func() { mockAuth.AssertExpectations(t) })
+
+	h := &Handler{auth: mockAuth, apiKey: "admin-key"}
+	resp, err := h.HandleRequest(ctx,
+		usageBookingLambdaRequest(map[string]string{"X-API-Key": "admin-key"},
+			"GET", "/api/auth/me/permissions"))
+
+	require.NoError(t, err)
+	require.Equal(t, 200, resp.StatusCode, "body: %s", resp.Body)
+	require.Empty(t, mockAuth.UsageBookings(), "the admin API key has no api_keys row to book against")
+}
diff --git a/internal/api/handler.go b/internal/api/handler.go
index 1bcb457f8..5da91e565 100644
--- a/internal/api/handler.go
+++ b/internal/api/handler.go
@@ -649,6 +649,18 @@ func (h *Handler) validateSecurityContext(ctx context.Context, req *events.Lambd
 	}
 	ctx = contextWithPrincipal(ctx, principal)
 
+	// Book the API key's usage here and nowhere else. This is the one code
+	// path that runs exactly once per inbound request, so it is the only
+	// place where a per-request counter can be incremented correctly. The
+	// credential itself is validated several times per request (here, then
+	// again by every permission check, and once per verb on the multi-verb
+	// gates), so booking inside auth.Service.ValidateUserAPIKey would count
+	// validations and inflate every reported number by a factor that varies
+	// per endpoint.
+	if principal.Kind == PrincipalUserAPIKey {
+		h.auth.RecordAPIKeyUsageAsync(principal.APIKeyID)
+	}
+
 	if h.requiresCSRFValidation(method, path, req) {
 		if err := h.validateCSRF(ctx, req); err != nil {
 			logging.Warnf("CSRF validation failed: %v", err)
diff --git a/internal/api/handler_ri_exchange_test.go b/internal/api/handler_ri_exchange_test.go
index d01e44a65..9c8c8b126 100644
--- a/internal/api/handler_ri_exchange_test.go
+++ b/internal/api/handler_ri_exchange_test.go
@@ -1052,6 +1052,7 @@ func (m *mockAuthForExchange) RevokeAPIKeyAPI(_ context.Context, _, _ string) er
 func (m *mockAuthForExchange) ValidateUserAPIKeyAPI(_ context.Context, _ string) (any, any, error) {
 	return nil, nil, nil
 }
+func (m *mockAuthForExchange) RecordAPIKeyUsageAsync(_ string) {}
 func (m *mockAuthForExchange) HasAPIKeyPermissionAPI(_ context.Context, _, _, _ string) (string, string, bool, error) {
 	return "admin", "", true, nil
 }
diff --git a/internal/api/middleware.go b/internal/api/middleware.go
index 76257e4d5..7a9e054c3 100644
--- a/internal/api/middleware.go
+++ b/internal/api/middleware.go
@@ -77,6 +77,12 @@ type Principal struct {
 	Session *Session // non-nil when a valid bearer session was presented
 	UserID  string   // empty for PrincipalAdminAPIKey
 	Email   string   // empty for PrincipalAdminAPIKey; populated for session/user-api-key
+	// APIKeyID is the database ID of the user API key the request
+	// authenticated with. Non-empty exactly when Kind is
+	// PrincipalUserAPIKey; empty for every other kind. It lets
+	// validateSecurityContext book the key's usage once per request without
+	// re-validating the credential.
+	APIKeyID string
 }
 
 type principalContextKey struct{}
@@ -136,13 +142,13 @@ func (h *Handler) authenticatePrincipal(ctx context.Context, req *events.LambdaF
 }
 
 // principalFromUserAPIKey resolves a Principal from a user API key.
-// Returns nil when the key is empty, validation fails, or the user record
-// cannot be retrieved.
+// Returns nil when the key is empty, validation fails, or the key/user
+// records cannot be retrieved.
 func (h *Handler) principalFromUserAPIKey(ctx context.Context, apiKey string) *Principal {
 	if apiKey == "" {
 		return nil
 	}
-	_, userRaw, err := h.auth.ValidateUserAPIKeyAPI(ctx, apiKey)
+	keyRaw, userRaw, err := h.auth.ValidateUserAPIKeyAPI(ctx, apiKey)
 	if err != nil {
 		logging.Debugf("User API key validation failed: %v", err)
 		return nil
@@ -158,10 +164,21 @@ func (h *Handler) principalFromUserAPIKey(ctx context.Context, apiKey string) *P
 		logging.Debugf("User API key: userRaw has unexpected type (%T); denying", userRaw)
 		return nil
 	}
+	// The key ID is required, not optional: it is what validateSecurityContext
+	// books usage against, so accepting a principal without one would silently
+	// stop counting that key's requests. A successful validation always yields
+	// the key row, so a missing or mistyped one is a broken invariant -- deny
+	// rather than authenticate a key we cannot attribute.
+	key, ok := keyRaw.(*auth.UserAPIKey)
+	if !ok || key == nil || key.ID == "" {
+		logging.Debugf("User API key: validation returned no usable key record (%T); denying", keyRaw)
+		return nil
+	}
 	return &Principal{
-		Kind:   PrincipalUserAPIKey,
-		UserID: user.ID,
-		Email:  user.Email,
+		Kind:     PrincipalUserAPIKey,
+		UserID:   user.ID,
+		Email:    user.Email,
+		APIKeyID: key.ID,
 	}
 }
 
diff --git a/internal/api/mocks_test.go b/internal/api/mocks_test.go
index 03a6c163a..c25658d06 100644
--- a/internal/api/mocks_test.go
+++ b/internal/api/mocks_test.go
@@ -2,6 +2,7 @@ package api
 
 import (
 	"context"
+	"sync"
 
 	"github.com/LeanerCloud/CUDly/internal/auth"
 	"github.com/LeanerCloud/CUDly/internal/config"
@@ -99,6 +100,32 @@ func (m *MockScheduler) GetRecommendationByID(ctx context.Context, id string) (*
 // MockAuthService is a mock implementation of the auth service.
 type MockAuthService struct {
 	mock.Mock
+	// usageBookingsMu guards usageBookings.
+	usageBookingsMu sync.Mutex
+	// usageBookings records every key ID passed to RecordAPIKeyUsageAsync,
+	// in call order. See that method for why it does not use mock.Mock.
+	usageBookings []string
+}
+
+// RecordAPIKeyUsageAsync records the booking instead of routing through
+// mock.Called. The handler books usage on every API-key-authenticated
+// request, so going through mock.Called would panic in each of the dozens of
+// existing tests that drive such a request without registering an
+// expectation. Recording into a slice keeps the calls observable --
+// UsageBookings() is what the exactly-once tests assert on -- without that
+// churn, and without the .Maybe() registration that would make the
+// assertions vacuous.
+func (m *MockAuthService) RecordAPIKeyUsageAsync(keyID string) {
+	m.usageBookingsMu.Lock()
+	defer m.usageBookingsMu.Unlock()
+	m.usageBookings = append(m.usageBookings, keyID)
+}
+
+// UsageBookings returns the key IDs booked so far, in call order.
+func (m *MockAuthService) UsageBookings() []string {
+	m.usageBookingsMu.Lock()
+	defer m.usageBookingsMu.Unlock()
+	return append([]string(nil), m.usageBookings...)
 }
 
 func (m *MockAuthService) Login(ctx context.Context, req LoginRequest) (*LoginResponse, error) {
diff --git a/internal/api/router_authuser_test.go b/internal/api/router_authuser_test.go
index ab6b2a52f..1dad0ddec 100644
--- a/internal/api/router_authuser_test.go
+++ b/internal/api/router_authuser_test.go
@@ -106,7 +106,7 @@ func TestRouterAuthUser_UserAPIKeyPrincipalAvoidsSecondValidation(t *testing.T)
 	ctx := context.Background()
 	mockAuth := new(MockAuthService)
 	user := &auth.User{ID: "api-key-user", Email: "user@example.com"}
-	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(nil, user, nil).Once()
+	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(&auth.UserAPIKey{ID: "key-1"}, user, nil).Once()
 	mockAuth.On("GetUserPermissionsAPI", mock.Anything, "api-key-user").Return([]auth.APIPermission{}, nil).Once()
 	h := &Handler{auth: mockAuth}
 	r := NewRouter(h)
@@ -162,7 +162,7 @@ func TestHandleRequest_UserAPIKeyPrincipalValidatedOnce(t *testing.T) {
 	ctx := context.Background()
 	mockAuth := new(MockAuthService)
 	user := &auth.User{ID: "api-key-user", Email: "user@example.com"}
-	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(nil, user, nil).Once()
+	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(&auth.UserAPIKey{ID: "key-1"}, user, nil).Once()
 	mockAuth.On("GetUserPermissionsAPI", mock.Anything, "api-key-user").Return([]auth.APIPermission{}, nil).Once()
 	h := &Handler{auth: mockAuth}
 	req := &events.LambdaFunctionURLRequest{
@@ -185,7 +185,7 @@ func TestHandleRequest_MixedCredentialsSessionOnlyHandlerUsesSession(t *testing.
 	mockAuth := new(MockAuthService)
 	apiUser := &auth.User{ID: "api-key-user", Email: "key@example.com"}
 	session := &Session{UserID: "session-user", Email: "session@example.com"}
-	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(nil, apiUser, nil).Once()
+	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(&auth.UserAPIKey{ID: "key-1"}, apiUser, nil).Once()
 	mockAuth.On("ValidateSession", ctx, "session-token").Return(session, nil).Once()
 	mockAuth.On("GetUser", mock.Anything, "session-user").Return(&User{ID: "session-user", Email: "session@example.com"}, nil).Once()
 	h := &Handler{auth: mockAuth}
@@ -210,7 +210,7 @@ func TestHandleRequest_MixedCredentialsAuthAdminRetainsAPIKeyRestrictions(t *tes
 	mockAuth := new(MockAuthService)
 	apiUser := &auth.User{ID: "api-key-user", Email: "key@example.com"}
 	session := &Session{UserID: "admin-session-user", Email: "admin@example.com"}
-	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(nil, apiUser, nil).Once()
+	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "user-key").Return(&auth.UserAPIKey{ID: "key-1"}, apiUser, nil).Once()
 	mockAuth.On("ValidateSession", ctx, "admin-session-token").Return(session, nil).Once()
 	mockAuth.On("HasPermissionAPI", mock.Anything, "admin-session-user", auth.ActionAdmin, auth.ResourceAll).Return(true, nil).Once()
 	mockAuth.On("HasAPIKeyPermissionAPI", mock.Anything, "user-key", auth.ActionView, auth.ResourceUsers).
@@ -307,7 +307,7 @@ func TestRequireAuth_UserAPIKey(t *testing.T) {
 
 	userRec := &auth.User{ID: "uid-123", Email: "alice@example.com"}
 	mockAuth.On("ValidateUserAPIKeyAPI", ctx, "valid-user-key").
-		Return(nil, userRec, nil)
+		Return(&auth.UserAPIKey{ID: "key-1"}, userRec, nil)
 
 	h := &Handler{auth: mockAuth}
 	req := &events.LambdaFunctionURLRequest{
diff --git a/internal/api/types.go b/internal/api/types.go
index 4bc985e5f..08a282341 100644
--- a/internal/api/types.go
+++ b/internal/api/types.go
@@ -215,6 +215,17 @@ type AuthServiceInterface interface {
 	DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error
 	RevokeAPIKeyAPI(ctx context.Context, userID, keyID string) error
 	ValidateUserAPIKeyAPI(ctx context.Context, apiKey string) (any, any, error)
+	// RecordAPIKeyUsageAsync books exactly one request against the given
+	// API key ID (the last_used_at timestamp plus the lifetime and
+	// fixed-window request counters). Fire-and-forget: the store write
+	// happens off the request path, so it returns nothing and never delays
+	// or fails the caller's request.
+	//
+	// Must be called once per inbound request and only from
+	// Handler.validateSecurityContext. Calling it from a credential
+	// validation path instead would count validations, which a single
+	// request performs several times over.
+	RecordAPIKeyUsageAsync(keyID string)
 	// HasAPIKeyPermissionAPI validates a user API key and checks the
 	// requested action/resource against the key's effective permissions
 	// (the intersection of the key's scoped permissions with the owning
diff --git a/internal/auth/service.go b/internal/auth/service.go
index fc1040836..ebb19b1a3 100644
--- a/internal/auth/service.go
+++ b/internal/auth/service.go
@@ -51,7 +51,7 @@ type Service struct {
 	// pendingUsage accumulates per-API-key request counts that have not yet
 	// been flushed to the store, keyed by API key ID. pendingUsageMu guards
 	// the map itself; the counters are incremented and drained atomically
-	// without it. See Service.recordUsageAsync for why the count is buffered
+	// without it. See Service.RecordUsageAsync for why the count is buffered
 	// instead of incremented once per flush.
 	pendingUsage       map[string]*atomic.Int64
 	pendingUsageMu     sync.Mutex
diff --git a/internal/auth/service_apikeys.go b/internal/auth/service_apikeys.go
index 54a3d24ca..8459c146f 100644
--- a/internal/auth/service_apikeys.go
+++ b/internal/auth/service_apikeys.go
@@ -276,6 +276,15 @@ func (s *Service) lookupAPIKeyUser(ctx context.Context, userID string) (*User, e
 }
 
 // ValidateUserAPIKey validates an API key and returns the key info and associated user.
+//
+// Validation is deliberately side-effect free: it books no usage. A single
+// HTTP request validates the same credential several times (authentication
+// resolves the principal, then every permission check re-validates, and the
+// multi-verb gates re-validate once per verb), so booking here would count
+// validations rather than requests and inflate every usage number by a
+// per-endpoint factor. Usage is booked exactly once per request by the API
+// layer -- see Handler.validateSecurityContext, which calls RecordUsageAsync
+// on the one code path guaranteed to run once per request.
 func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserAPIKey, *User, error) {
 	hash := sha256.Sum256([]byte(apiKey))
 	keyHash := base64.RawURLEncoding.EncodeToString(hash[:])
@@ -305,14 +314,17 @@ func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserA
 		return nil, nil, err
 	}
 
-	s.recordUsageAsync(key.ID)
-
 	return key, user, nil
 }
 
-// recordUsageAsync books one request against keyID and flushes the pending
+// RecordUsageAsync books one request against keyID and flushes the pending
 // count to the store off the authentication hot path.
 //
+// Callers must invoke this exactly once per inbound request, not once per
+// credential validation -- a single request validates the same key several
+// times over. The API layer owns that guarantee (see
+// Handler.validateSecurityContext).
+//
 // The count is accumulated in memory first and the flush writes the whole
 // accumulated delta, because singleflight.Group collapses concurrent flushes
 // for the same key into one DB write. Incrementing by a fixed 1 inside the
@@ -323,7 +335,7 @@ func (s *Service) ValidateUserAPIKey(ctx context.Context, apiKey string) (*UserA
 // singleflight is still what bounds the write rate: at most one in-flight DB
 // write per keyID at any moment, so a flood of requests on one key cannot
 // amplify into a flood of database writes.
-func (s *Service) recordUsageAsync(keyID string) {
+func (s *Service) RecordUsageAsync(keyID string) {
 	// Book the request BEFORE starting the flush goroutine, so it can never
 	// be missed by a flush that is already draining the counter.
 	s.addPendingUsage(keyID)
diff --git a/internal/auth/service_apikeys_api.go b/internal/auth/service_apikeys_api.go
index c1d9c6c40..5772dbbdc 100644
--- a/internal/auth/service_apikeys_api.go
+++ b/internal/auth/service_apikeys_api.go
@@ -191,7 +191,14 @@ func (s *Service) CreateAPIKeyAPI(ctx context.Context, userID string, req any) (
 		return nil, err
 	}
 
-	// Convert to API response
+	// Convert to API response. keyInfo is the struct CreateAPIKey just built
+	// in memory, so its counters are necessarily zero and the window start
+	// nil -- exactly what effectiveWindowUsage returns for them. It still
+	// goes through the helper so every window-counter exposure site shares
+	// one implementation: the day CreateAPIKey re-reads the inserted row, a
+	// raw field read here would silently start reporting a stale window
+	// while the list and stats endpoints report it correctly.
+	windowCount, windowStart := effectiveWindowUsage(keyInfo, time.Now())
 	return &APICreateAPIKeyResponse{
 		APIKey: apiKey,
 		KeyID:  keyInfo.ID,
@@ -205,8 +212,8 @@ func (s *Service) CreateAPIKeyAPI(ctx context.Context, userID string, req any) (
 			LastUsedAt:              keyInfo.LastUsedAt,
 			IsActive:                keyInfo.IsActive,
 			RequestCountTotal:       effectiveLifetimeUsage(keyInfo),
-			RequestCountWindow:      keyInfo.RequestCountWindow,
-			RequestCountWindowStart: keyInfo.RequestCountWindowStart,
+			RequestCountWindow:      windowCount,
+			RequestCountWindowStart: windowStart,
 		},
 	}, nil
 }
diff --git a/internal/auth/service_apikeys_api_test.go b/internal/auth/service_apikeys_api_test.go
index e1996d70a..925494bc6 100644
--- a/internal/auth/service_apikeys_api_test.go
+++ b/internal/auth/service_apikeys_api_test.go
@@ -495,14 +495,16 @@ func TestService_ValidateUserAPIKeyAPI(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKeyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).Return(nil).Maybe()
+		// No RecordAPIKeyUsage expectation: validation books no usage, so
+		// there is no background goroutine to wait for either. Usage is
+		// booked once per request by the API layer -- see
+		// Handler.validateSecurityContext.
 
 		resultKey, resultUser, err := service.ValidateUserAPIKeyAPI(ctx, apiKey)
 
 		require.NoError(t, err)
 		assert.Equal(t, apiKeyRecord, resultKey)
 		assert.Equal(t, user, resultUser)
-		time.Sleep(10 * time.Millisecond) // Allow goroutine to complete
 		mockStore.AssertExpectations(t)
 	})
 
diff --git a/internal/auth/service_apikeys_test.go b/internal/auth/service_apikeys_test.go
index 3efd22607..2366b98c3 100644
--- a/internal/auth/service_apikeys_test.go
+++ b/internal/auth/service_apikeys_test.go
@@ -512,23 +512,35 @@ func TestService_ValidateUserAPIKey(t *testing.T) {
 
 		mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKeyRecord, nil)
 		mockStore.On("GetUserByID", ctx, "user-123").Return(user, nil)
-		// Use a signaling channel + .Once() so the test fails (rather than
-		// silently passes) if ValidateUserAPIKey ever stops recording usage,
-		// and so we don't have to busy-sleep waiting for the async goroutine.
+		// Validation must book NO usage: one HTTP request validates the same
+		// credential several times, so counting here would multiply every
+		// reported figure. The API layer books once per request instead --
+		// see Handler.validateSecurityContext and the exactly-once tests in
+		// internal/server/apikey_usage_booking_test.go.
+		//
+		// Registered with .Maybe() rather than left unregistered because an
+		// unexpected call would panic inside the flush goroutine, where
+		// RecordUsageAsync's recover() would swallow it and the test would
+		// pass regardless.
 		usageRecorded := make(chan struct{}, 1)
 		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).
 			Run(func(mock.Arguments) { usageRecorded <- struct{}{} }).
-			Return(nil).Once()
+			Return(nil).Maybe()
 
 		resultKey, resultUser, err := service.ValidateUserAPIKey(ctx, apiKey)
 
 		require.NoError(t, err)
 		assert.Equal(t, user, resultUser)
 		assert.Equal(t, apiKeyRecord, resultKey)
+		// A booking would be flushed by a goroutine started before
+		// ValidateUserAPIKey returned, so a bounded quiet window is the only
+		// way to establish its absence. Unlike the positive waits elsewhere
+		// in this suite (where too short a deadline flakes), too short a
+		// window here can only miss a regression, never fail spuriously.
 		select {
 		case <-usageRecorded:
-		case <-time.After(5 * time.Second):
-			t.Fatal("expected RecordAPIKeyUsage to be called")
+			t.Fatal("ValidateUserAPIKey must not record usage: booking on the validation path counts validations, not requests")
+		case <-time.After(2 * time.Second):
 		}
 		mockStore.AssertExpectations(t)
 	})
@@ -781,7 +793,7 @@ func TestService_FlushPendingUsage(t *testing.T) {
 		service := &Service{store: mockStore}
 
 		// A request that lands while the write is in flight must still be
-		// pending afterwards -- recordUsageAsync's loop picks it up.
+		// pending afterwards -- RecordUsageAsync's loop picks it up.
 		mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", int64(2)).
 			Run(func(mock.Arguments) { service.addPendingUsage("key-1") }).
 			Return(nil).Once()
@@ -832,7 +844,7 @@ func TestService_RecordUsageAsync_CountsConcurrentRequests(t *testing.T) {
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			service.recordUsageAsync("key-1")
+			service.RecordUsageAsync("key-1")
 		}()
 	}
 	wg.Wait()
@@ -1122,38 +1134,21 @@ func TestService_HasAPIKeyPermissionForConstraintsAPI_OwnerCapEnforced(t *testin
 	})
 }
 
-// TestValidateUserAPIKey_UpdateLastUsedPanicIsRecovered proves that a panic
-// inside the fire-and-forget RecordUsage goroutine is caught by the
-// recover() added in issue #672. Without the recover(), the panic would crash
-// the entire test binary (an unrecovered goroutine panic terminates the
-// process). The test uses a channel -- closed by the mock Run callback just
-// before panicking -- to wait for goroutine execution without time.Sleep.
-func TestValidateUserAPIKey_UpdateLastUsedPanicIsRecovered(t *testing.T) {
-	ctx := context.Background()
-
-	apiKey := "test-api-key-panic-123"
-	hash := sha256.Sum256([]byte(apiKey))
-	keyHash := base64.RawURLEncoding.EncodeToString(hash[:])
-
-	user := &User{
-		ID:     "user-panic",
-		Email:  "panic@example.com",
-		Active: true,
-	}
-	apiKeyRecord := &UserAPIKey{
-		ID:       "key-panic",
-		UserID:   "user-panic",
-		KeyHash:  keyHash,
-		IsActive: true,
-	}
-
+// TestRecordUsageAsync_PanicIsRecovered proves that a panic inside the
+// fire-and-forget RecordUsage goroutine is caught by the recover() added in
+// issue #672. Without the recover(), the panic would crash the entire test
+// binary (an unrecovered goroutine panic terminates the process). The test
+// uses a channel -- closed by the mock Run callback just before panicking --
+// to wait for goroutine execution without time.Sleep.
+//
+// Driven through RecordUsageAsync directly rather than through
+// ValidateUserAPIKey, which no longer books usage (booking moved to the API
+// layer so it happens once per request rather than once per validation).
+func TestRecordUsageAsync_PanicIsRecovered(t *testing.T) {
 	mockStore := new(MockStore)
 	service := &Service{store: mockStore}
 	t.Cleanup(func() { mockStore.AssertExpectations(t) })
 
-	mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKeyRecord, nil)
-	mockStore.On("GetUserByID", mock.Anything, "user-panic").Return(user, nil)
-
 	// done is closed by the Run callback immediately before panicking so the
 	// test can wait for goroutine execution without time.Sleep.
 	done := make(chan struct{})
@@ -1164,10 +1159,7 @@ func TestValidateUserAPIKey_UpdateLastUsedPanicIsRecovered(t *testing.T) {
 		}).
 		Return(nil)
 
-	resultKey, resultUser, err := service.ValidateUserAPIKey(ctx, apiKey)
-	require.NoError(t, err)
-	require.Equal(t, apiKeyRecord, resultKey)
-	require.Equal(t, user, resultUser)
+	service.RecordUsageAsync("key-panic")
 
 	// Block until the goroutine has executed (and panicked + recovered).
 	// Reaching this line means the process survived -- recover() caught the panic.
diff --git a/internal/auth/service_security_test.go b/internal/auth/service_security_test.go
index 864a22ba9..0c735f9f3 100644
--- a/internal/auth/service_security_test.go
+++ b/internal/auth/service_security_test.go
@@ -6,8 +6,6 @@ package auth
 
 import (
 	"context"
-	"crypto/sha256"
-	"encoding/base64"
 	"testing"
 	"time"
 
@@ -217,51 +215,33 @@ func TestCSRFToken_CrossSessionRejected(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// #1027 — ValidateUserAPIKey uses singleflight (no panic under concurrency)
+// #1027 — RecordUsageAsync uses singleflight (no panic under concurrency)
 // ---------------------------------------------------------------------------
 
-// TestValidateUserAPIKey_LastUsedSingleflight verifies that ValidateUserAPIKey
-// does not panic when called, and that the background last-used update
-// completes without errors. The singleflight fix ensures concurrent requests
-// for the same key do not spawn unbounded goroutines.
-func TestValidateUserAPIKey_LastUsedSingleflight(t *testing.T) {
-	ctx := context.Background()
+// TestRecordUsageAsync_Singleflight verifies that a usage booking does not
+// panic, and that the background counter write completes without errors. The
+// singleflight fix ensures concurrent requests for the same key do not spawn
+// unbounded goroutines.
+//
+// Booking used to hang off ValidateUserAPIKey, which is why this test was
+// originally written against it; usage is now booked once per request by the
+// API layer, so the goroutine is exercised through RecordUsageAsync directly.
+func TestRecordUsageAsync_Singleflight(t *testing.T) {
 	mockStore := new(MockStore)
 	t.Cleanup(func() { mockStore.AssertExpectations(t) })
 	service := createTestService(mockStore, new(MockEmailSender))
 
-	rawKey := "test-api-key-singleflight"
-	h := sha256.Sum256([]byte(rawKey))
-	keyHash := base64.RawURLEncoding.EncodeToString(h[:])
 	keyID := "sfg-key-id"
 
-	user := &User{
-		ID:     "sfg-user",
-		Email:  "sfg@example.com",
-		Active: true,
-	}
-	apiKey := &UserAPIKey{
-		ID:        keyID,
-		UserID:    user.ID,
-		IsActive:  true,
-		KeyHash:   keyHash,
-		KeyPrefix: rawKey[:8],
-	}
-
 	// done is closed by the mock's Run callback when RecordAPIKeyUsage is
 	// invoked, confirming the background goroutine ran to completion without
 	// relying on time.Sleep.
 	done := make(chan struct{})
-	mockStore.On("GetAPIKeyByHash", ctx, keyHash).Return(apiKey, nil).Maybe()
-	mockStore.On("GetUserByID", ctx, user.ID).Return(user, nil).Maybe()
 	mockStore.On("RecordAPIKeyUsage", mock.Anything, keyID, mock.Anything).
 		Run(func(args mock.Arguments) { close(done) }).
 		Return(nil).Once()
 
-	gotKey, gotUser, err := service.ValidateUserAPIKey(ctx, rawKey)
-	require.NoError(t, err)
-	assert.Equal(t, keyID, gotKey.ID)
-	assert.Equal(t, user.ID, gotUser.ID)
+	service.RecordUsageAsync(keyID)
 
 	// Wait for the background goroutine to invoke RecordAPIKeyUsage.
 	select {
diff --git a/internal/auth/store_postgres_apikeys.go b/internal/auth/store_postgres_apikeys.go
index fe6c8c316..43ec0a9de 100644
--- a/internal/auth/store_postgres_apikeys.go
+++ b/internal/auth/store_postgres_apikeys.go
@@ -182,7 +182,7 @@ func (s *PostgresStore) UpdateAPIKeyLastUsed(ctx context.Context, keyID string)
 //
 // delta is the number of requests being recorded in this flush. The auth hot
 // path coalesces concurrent requests for the same key into a single write
-// (see Service.recordUsageAsync), so delta is frequently greater than 1 and
+// (see Service.RecordUsageAsync), so delta is frequently greater than 1 and
 // must be added rather than treated as a single increment.
 //
 // request_count_window is a FIXED/TUMBLING window counter, not a true
diff --git a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
index 5de0e5f43..41afd3181 100644
--- a/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
+++ b/internal/database/postgres/migrations/000094_api_keys_usage_counters.up.sql
@@ -15,7 +15,8 @@
 --                                  just before the window resets is
 --                                  discarded from the count as soon as the
 --                                  next request starts a new window. See
---                                  store_postgres.go RecordAPIKeyUsage.
+--                                  store_postgres_apikeys.go
+--                                  RecordAPIKeyUsage.
 --                                  NOTE the restart only happens on the
 --                                  key's NEXT request, so an idle key keeps
 --                                  its closed window's count in this column
diff --git a/internal/server/apikey_usage_booking_test.go b/internal/server/apikey_usage_booking_test.go
new file mode 100644
index 000000000..06602b9ad
--- /dev/null
+++ b/internal/server/apikey_usage_booking_test.go
@@ -0,0 +1,220 @@
+package server
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/LeanerCloud/CUDly/internal/api"
+	"github.com/LeanerCloud/CUDly/internal/auth"
+	"github.com/aws/aws-lambda-go/events"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+// API key usage must be booked once per HTTP REQUEST, never once per
+// credential validation.
+//
+// A single request validates the same API key several times over: once to
+// resolve the principal, then again inside every permission check, and once
+// per verb on the multi-verb gates. While the async write was an idempotent
+// last_used_at timestamp that multiplicity was harmless, but PR #1523 turned
+// it into an additive counter, so booking on the validation path multiplied
+// every reported number by a factor that varies per endpoint (2x on a plain
+// gate, 5x on the four-verb purchase gate) and therefore cannot be divided
+// back out of the stored totals.
+//
+// These tests live in package server rather than package api because they
+// need the REAL auth.Service behind the handler: with api's mock auth service
+// both the validation and the permission check are stubbed, so no booking
+// path is exercised at all and the regression is structurally invisible. The
+// same reason rules out a pure auth-package test -- the multiplicity comes
+// from the handler calling down repeatedly, which only shows up when both
+// layers are wired together.
+
+// usageBookingRawKey is the raw API key value the harness authenticates with.
+const usageBookingRawKey = "usage-booking-harness-api-key" // #nosec G101 -- test fixture, not a real credential
+
+// usageBookingKeyHash mirrors how auth.Service.ValidateUserAPIKey derives the
+// stored hash from the presented key, so the store mock can be keyed on it.
+func usageBookingKeyHash() string {
+	sum := sha256.Sum256([]byte(usageBookingRawKey))
+	return base64.RawURLEncoding.EncodeToString(sum[:])
+}
+
+// usageBookingHarness wires a real auth.Service (over a mock store) into a
+// real api.Handler and observes both how many times a request re-validates
+// the credential and how much usage reaches the store.
+type usageBookingHarness struct {
+	handler *api.Handler
+	// flushes receives the delta of every RecordAPIKeyUsage call.
+	flushes chan int64
+	// totalDelta is the sum of all deltas written to the store.
+	totalDelta atomic.Int64
+	// validations counts credential validations. Every
+	// ValidateUserAPIKey begins with exactly one GetAPIKeyByHash, so this
+	// is the per-request multiplier the fix has to decouple usage from.
+	validations atomic.Int64
+}
+
+// newUsageBookingHarness builds the harness. groupPermissions are granted to
+// the key owner's group; the API key itself carries no explicit permissions,
+// so it inherits the owner's set.
+func newUsageBookingHarness(t *testing.T, groupPermissions []auth.Permission) *usageBookingHarness {
+	t.Helper()
+
+	h := &usageBookingHarness{
+		// Buffered well past the worst observed booking count so a flush
+		// goroutine can never block on the test.
+		flushes: make(chan int64, 64),
+	}
+
+	keyHash := usageBookingKeyHash()
+	key := &auth.UserAPIKey{
+		ID:       "key-1",
+		UserID:   "user-1",
+		Name:     "usage booking harness",
+		KeyHash:  keyHash,
+		IsActive: true,
+	}
+	user := &auth.User{
+		ID:       "user-1",
+		Email:    "harness@example.com",
+		Active:   true,
+		GroupIDs: []string{"group-1"},
+	}
+	group := &auth.Group{ID: "group-1", Name: "harness", Permissions: groupPermissions}
+
+	mockStore := new(auth.MockStore)
+	t.Cleanup(func() { mockStore.AssertExpectations(t) })
+
+	mockStore.On("GetAPIKeyByHash", mock.Anything, keyHash).
+		Run(func(mock.Arguments) { h.validations.Add(1) }).
+		Return(key, nil)
+	mockStore.On("GetUserByID", mock.Anything, "user-1").Return(user, nil)
+	mockStore.On("GetGroup", mock.Anything, "group-1").Return(group, nil).Maybe()
+	mockStore.On("ListAPIKeysByUser", mock.Anything, "user-1").
+		Return([]*auth.UserAPIKey{key}, nil).Maybe()
+	mockStore.On("RecordAPIKeyUsage", mock.Anything, "key-1", mock.Anything).
+		Run(func(args mock.Arguments) {
+			// Runs on the flush goroutine: only atomics and a non-blocking
+			// send here, never a require.* call.
+			delta, ok := args.Get(2).(int64)
+			if !ok {
+				// Surfaces as a negative total, failing the assertion loudly
+				// rather than panicking into RecordUsageAsync's recover().
+				delta = -1
+			}
+			h.totalDelta.Add(delta)
+			select {
+			case h.flushes <- delta:
+			default:
+			}
+		}).
+		Return(nil).Maybe()
+
+	service := auth.NewService(auth.ServiceConfig{
+		Store:           mockStore,
+		SessionDuration: time.Hour,
+		CSRFKey:         auth.TestCSRFKey(),
+	})
+	h.handler = api.NewHandler(api.HandlerConfig{
+		AuthService:       newAuthServiceAdapter(service),
+		CORSAllowedOrigin: "https://dashboard.example.com",
+	})
+	return h
+}
+
+// request builds an API-key-authenticated Lambda Function URL request.
+func (h *usageBookingHarness) request(method, path string) *events.LambdaFunctionURLRequest {
+	return &events.LambdaFunctionURLRequest{
+		Headers: map[string]string{"x-api-key": usageBookingRawKey},
+		RequestContext: events.LambdaFunctionURLRequestContext{
+			HTTP: events.LambdaFunctionURLRequestContextHTTPDescription{Method: method, Path: path},
+		},
+	}
+}
+
+// requireExactlyOneBooking asserts the request booked exactly one request
+// against the key.
+//
+// The bookings themselves are synchronous -- RecordUsageAsync increments an
+// in-memory counter before returning -- so by the time HandleRequest returns,
+// every booking the request will ever make has already been made; only the
+// flush to the store runs on a goroutine. With the bug present the surplus
+// bookings therefore surface either as a first flush carrying a delta above 1
+// or as a second flush arriving microseconds later, and both are caught here.
+// The second half needs a bounded quiet window rather than a channel receive
+// because it is proving the ABSENCE of a further write. Note the two waits are
+// not symmetric: the first is a positive wait, where too short a deadline
+// causes a flaky FAILURE, so it is generous. The second is a negative wait,
+// where too short a window can only cause a missed detection (a false PASS),
+// never a flake -- and the surplus flush it is looking for comes from a
+// goroutine already running before HandleRequest returned, so it lands within
+// microseconds and the window is orders of magnitude wider than needed.
+func (h *usageBookingHarness) requireExactlyOneBooking(t *testing.T) {
+	t.Helper()
+
+	select {
+	case delta := <-h.flushes:
+		require.EqualValues(t, 1, delta,
+			"one HTTP request must book exactly 1 usage; the first flush wrote %d", delta)
+	case <-time.After(10 * time.Second):
+		t.Fatal("no API key usage reached the store")
+	}
+
+	select {
+	case delta := <-h.flushes:
+		t.Fatalf("a second flush booked %d more usage(s) (total %d): usage is being counted per credential validation, not per request",
+			delta, h.totalDelta.Load())
+	case <-time.After(2 * time.Second):
+	}
+
+	require.EqualValues(t, 1, h.totalDelta.Load(),
+		"total usage booked for one HTTP request")
+}
+
+// TestHandleRequest_UserAPIKey_BooksOneUsagePerRequest pins the single-verb
+// path: GET /api/api-keys/usage-stats authenticates the key once and then
+// re-validates it inside the view:api-keys permission check, so booking on
+// the validation path reported one request as two.
+func TestHandleRequest_UserAPIKey_BooksOneUsagePerRequest(t *testing.T) {
+	h := newUsageBookingHarness(t, []auth.Permission{
+		{Action: auth.ActionView, Resource: auth.ResourceAPIKeys},
+	})
+
+	resp, err := h.handler.HandleRequest(context.Background(),
+		h.request("GET", "/api/api-keys/usage-stats"))
+
+	require.NoError(t, err)
+	require.Equal(t, 200, resp.StatusCode, "body: %s", resp.Body)
+	require.Greater(t, h.validations.Load(), int64(1),
+		"harness precondition: this endpoint must re-validate the credential, otherwise it cannot detect per-validation booking")
+	h.requireExactlyOneBooking(t)
+}
+
+// TestHandleRequest_UserAPIKeyMultiVerbGate_BooksOneUsagePerRequest pins the
+// worst case: requireDeleteOrCancelPurchasePermission walks four verbs and
+// authorizeAPIKeyAny re-validates the credential once per verb, so booking on
+// the validation path reported one request as five.
+//
+// The key holds none of the four verbs, so the gate walks the entire list.
+// The resulting 403 is incidental -- what is pinned is that an authenticated
+// request books one usage no matter how many permission checks it triggers.
+func TestHandleRequest_UserAPIKeyMultiVerbGate_BooksOneUsagePerRequest(t *testing.T) {
+	h := newUsageBookingHarness(t, []auth.Permission{
+		{Action: auth.ActionView, Resource: auth.ResourceRecommendations},
+	})
+
+	resp, err := h.handler.HandleRequest(context.Background(),
+		h.request("DELETE", "/api/purchases/planned/11111111-1111-1111-1111-111111111111"))
+
+	require.NoError(t, err)
+	require.Equal(t, 403, resp.StatusCode, "body: %s", resp.Body)
+	require.GreaterOrEqual(t, h.validations.Load(), int64(5),
+		"harness precondition: the four-verb gate must re-validate the credential once per verb")
+	h.requireExactlyOneBooking(t)
+}
diff --git a/internal/server/app.go b/internal/server/app.go
index b93f7405f..fcdbfe845 100644
--- a/internal/server/app.go
+++ b/internal/server/app.go
@@ -1194,6 +1194,10 @@ func (a *authServiceAdapter) ValidateUserAPIKeyAPI(ctx context.Context, apiKey s
 	return a.service.ValidateUserAPIKeyAPI(ctx, apiKey)
 }
 
+func (a *authServiceAdapter) RecordAPIKeyUsageAsync(keyID string) {
+	a.service.RecordUsageAsync(keyID)
+}
+
 func (a *authServiceAdapter) HasAPIKeyPermissionAPI(ctx context.Context, apiKey, action, resource string) (userID, keyID string, allowed bool, err error) {
 	userID, keyID, allowed, err = a.service.HasAPIKeyPermissionAPI(ctx, apiKey, action, resource)
 	return