feat(apollo): track lastUsedAt on project API keys (T-10454)

@zen-agentchecks n/achecks…zen/fix-api-key-last-used-1nl8c0 → master10 files · +323 −7review: @sohamganatrareview: @kaavee315review: @lingalarahul7review: @anshugarg15review: @abir-taheerupdated 1mo ago

GitHub

▸Description· 1 comment · 6 noise

Description

Customer ticket T-10454 (Kaden / askelephant.ai) — the dashboard "Last Used" column on the API Keys settings page always rendered Never, even for keys that were actively in use.

Root cause: the feature was never implemented end-to-end.

The ApiKey (project_api_keys) table had no lastUsedAt column.
The auth path getAPIKeyInfo performs zero writes — there was nothing tracking key usage.
The list response in api_keys/list.ts:165 and lib/apiKeys/listAPIKeys.ts:29 hardcoded last_used: undefined, so the dashboard's apiKey.last_used ? formatDate(...) : "Never" branch always picked "Never".

This PR wires the feature end-to-end:

DB — adds nullable lastUsedAt to the ApiKey model (packages/db/prisma/schema.prisma) and a Liquibase v87 migration that adds the column to public.project_api_keys. Existing rows get NULL ("no usage recorded yet"), which the dashboard renders as Never — honest, since we have no historical data for them.
Auth (throttled write) — getAPIKeyInfo (called on every authenticated request) now calls markAPIKeyUsed(apiKeyId) fire-and-forget after a successful cache/DB lookup. The helper uses redis.SETNX api_key_used:<id> with a 5-minute TTL as an atomic throttle: the first call in the window writes lastUsedAt = now() via the new DB_API_KEY.markUsed, subsequent calls in the same window short-circuit. Caps DB writes to at most once per key per 5 minutes — flat pressure even under high QPS. Errors are logged at debug level; they never surface to the auth path.
API surface — last_used now returns apiKey.lastUsedAt?.toISOString() in both pages/api/v3/org/project/[projectId]/api_keys/list.ts (the dashboard endpoint, reached at both /api/v3/... and /api/v3.1/... via the v3.1→v3 proxy rewrite) and lib/apiKeys/listAPIKeys.ts (the internal helper used by MCP/session-info). The OpenAPI schema field was already declared optional, so no client SDK regen impact.

The dashboard frontend (api-keys-table.tsx:64) was already doing the right thing — it renders last_used when present and falls back to "Never". No frontend change needed.

How did I test this PR

Unit/integration tests (run against the local Neon fork) — added a new test in api-keys.test.ts that exercises the full round-trip: seed a key via DB_API_KEY.createAPIKey, assert lastUsedAt = null in DB, call DB_API_KEY.markUsed, assert the DB column updated, then hit the list endpoint and assert last_used equals the stored timestamp's ISO string.

cd /workspace/hermes/apps/apollo
doppler run -- pnpm with-env vitest run src/pages/api/v3/org/project/[projectId]/api_keys/api-keys.test.ts
# Test Files  1 passed (1)
#      Tests  12 passed (12)

All 12 tests pass, including the new "API Keys last_used surfaces in list response" case.

Type checking + lint — clean:

cd /workspace/hermes/apps/apollo
pnpm check-types   # passes, no errors
pnpm lint          # 0 errors (1 pre-existing warning unrelated to this PR)

Migration locally verified — ran the up.ts SQL against the local DB and confirmed the column appears in \d project_api_keys with timestamp(3) without time zone. The down.ts is the inverse (DROP COLUMN IF EXISTS). Both are idempotent.

Manual reasoning on the throttle — redis.SETNX with EX 300 is atomic, so concurrent auth requests from many SDK clients can't dogpile the DB. Cache miss on setIfNotExists (which only happens on Redis errors) is handled by logging and skipping — auth still succeeds, we just don't update lastUsedAt that call. A successful auth never blocks on the throttle write either, because we use void markAPIKeyUsed(...).

🤖 Generated with Claude Code

@zen-agent1mo ago

Post-PR status update

Build checks (/build-checks): all green

doppler run -- pnpm lint — PASS (1 pre-existing warning untouched)
doppler run -- pnpm format:check — PASS
doppler run -- pnpm check-types — PASS

Codex review (/codex-review-loop): 2 iterations

Iteration 1: 1 P2 finding — "Schedule last-used writes with waitUntil" (Vercel could kill the unawaited Redis/Prisma chain after the response is sent). Fixed in 6c673ba087 by wrapping markAPIKeyUsed in waitUntil from @vercel/functions, mirroring the existing scheduleMeteringBackgroundWork pattern.
Iteration 2: LGTM — "No discrete, introduced correctness issues were found in the diff. The new nullable column is surfaced consistently in the listing paths, and the background last-used update is throttled and non-blocking."

Cursor Bugbot: 1 low-severity finding — "Throttle key not cleared on DB write failure". Fixed in 17f4a21fc1 (redisProvider.del() the throttle on DB failure so the next request retries instead of waiting the full 5-min window) and replied inline.

Testing checklist

Unit/integration test added (api-keys.test.ts → "API Keys last_used surfaces in list response") exercising the full round-trip: createAPIKey → assert lastUsedAt = null → DB_API_KEY.markUsed → assert DB write → list endpoint → assert response last_used equals stored ISO string. 12/12 tests pass.
Local Apollo runtime sanity check: GET /api/healthz → 200, GET /api/v3/tools/HACKERNEWS_GET_FRONTPAGE (via project API key) → 200 with expected payload (auth path is exercised).

CI: pending — re-running after second commit (first run had a flaky run-vitest-e2e-tests failure on the unrelated rerouted/v2/actions/[actionId]/execute.test.e2e.ts suite; master Vitest E2E on the current HEAD is green so this was infrastructure flakiness, not a code regression).

▸ 6 bot/status comments hidden

@vercel[bot]1mo ago

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
apollo	Ready	Preview, Comment	May 13, 2026 11:12am

Project	Deployment	Actions	Updated (UTC)
debby	Skipped		May 13, 2026 11:12am

@github-actions[bot]1mo ago

🔍 Suggested Reviewers

Based on git blame analysis of 10 file(s):

Contributor	Contribution	Files
anshugarg15	24%	6
Zen	20%

loading diff…

@zen-agent1mo ago

Post-PR status update

Build checks (/build-checks): all green

doppler run -- pnpm lint — PASS (1 pre-existing warning untouched)
doppler run -- pnpm format:check — PASS
doppler run -- pnpm check-types — PASS

Codex review (/codex-review-loop): 2 iterations

Iteration 1: 1 P2 finding — "Schedule last-used writes with waitUntil" (Vercel could kill the unawaited Redis/Prisma chain after the response is sent). Fixed in 6c673ba087 by wrapping markAPIKeyUsed in waitUntil from @vercel/functions, mirroring the existing scheduleMeteringBackgroundWork pattern.
Iteration 2: LGTM — "No discrete, introduced correctness issues were found in the diff. The new nullable column is surfaced consistently in the listing paths, and the background last-used update is throttled and non-blocking."

Testing checklist

Unit/integration test added (api-keys.test.ts → "API Keys last_used surfaces in list response") exercising the full round-trip: createAPIKey → assert lastUsedAt = null → DB_API_KEY.markUsed → assert DB write → list endpoint → assert response last_used equals stored ISO string. 12/12 tests pass.
Local Apollo runtime sanity check: GET /api/healthz → 200, GET /api/v3/tools/HACKERNEWS_GET_FRONTPAGE (via project API key) → 200 with expected payload (auth path is exercised).

Files with missing lines	Patch %	Lines
apps/apollo/src/lib/apiKeys/getAPIKey.ts	52.00%	24 Missing :warning:
apps/apollo/src/lib/apiKeys/dbUtils/index.ts	61.11%	7 Missing :warning:

Flag	Coverage Δ
e2e-tests	`5.81% <1.42%> (-0.01%)`	:arrow_down:
self-hosted-tests	`5.64% <1.42%> (-0.01%)`	:arrow_down:
thermos-service-isolation-tests	`?`
thermos-unit-tests	`?`
unit-tests	`58.77% <55.71%> (+0.01%)`	:arrow_up:

Files with missing lines	Coverage Δ
apps/apollo/src/lib/apiKeys/listAPIKeys.ts	`91.30% <100.00%> (ø)`
...es/api/v3/org/project/[projectId]/api_keys/list.ts	`80.21% <100.00%> (ø)`
apps/apollo/src/lib/apiKeys/dbUtils/index.ts	`60.17% <61.11%> (+0.02%)`	:arrow_up:
apps/apollo/src/lib/apiKeys/getAPIKey.ts	`73.07% <52.00%> (-9.95%)`	:arrow_down:

feat(apollo): track lastUsedAt on project API keys (T-10454)

Description

How did I test this PR

Post-PR status update

🔍 Suggested Reviewers

Description

How did I test this PR

Post-PR status update

🔍 Suggested Reviewers

💡 Recommendation

🧪 Test Results Summary (Self-Hosted Tests)

🧪 Test Results Summary (Unit Tests)

Codecov Report

🧪 Test Results Summary (E2E Tests)