feat: track API key last usage timestamp

[seapagan]

Summary

• Add last_used_at field to ApiKey model to track when API keys are used
• Update timestamp in ApiKeyAuth.__call__() on successful authentication
• Expose field in ApiKeyResponse schema for security auditing
• Add database migration for the new column
• Add test to verify timestamp updates correctly

This enables identification of stale/unused API keys for security audits.

Closes SECURITY-REVIEW.md #23

Summary by CodeRabbit

• New Features

  • API Keys now include a last usage timestamp that is automatically updated upon successful authentication.
  • The timestamp is exposed in API key responses for visibility and tracking.

• Tests

  • Added test coverage verifying last usage timestamp updates during authentication.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request adds API key usage tracking by introducing a last_used_at timestamp field. The changes include a database migration, model field addition, authentication logic to update the timestamp on successful verification, schema exposure, and corresponding tests.

Changes

Cohort / File(s)	Summary
Database Schema app/migrations/versions/2026_01_23_2115-add_last_used_at_to_api_keys.py	Alembic migration adds nullable DateTime column last_used_at to api_keys table with downgrade support.
Model & Response app/models/api_key.py, app/schemas/response/api_key.py	ApiKey model field added for last_used_at timestamp; ApiKeyResponse schema exposes the new optional field.
Authentication Logic app/managers/api_key.py	ApiKeyAuth.call() updated to set last_used_at to current UTC time after successful authentication.
Test Coverage tests/unit/test_api_key_auth.py	New test verifies that successful API key authentication updates last_used_at from None to a timestamp value.

Sequence Diagram

sequenceDiagram
    actor Client
    participant Auth as ApiKeyAuth
    participant DB as Database<br/>(api_keys)
    
    Client->>Auth: Request with API key
    Auth->>Auth: Validate API key
    Auth->>Auth: Set request.state.api_key
    Auth->>DB: Update last_used_at = now()
    DB-->>Auth: Timestamp updated
    Auth-->>Client: Authentication successful

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

security

Poem

🐰 A hop, a skip, and keys track time,
Last used moments marked so fine,
Authentication leaves its trace,
Timestamps dancing through cyberspace! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and concisely summarizes the main change: adding API key last usage timestamp tracking. It is specific, relevant, and reflects the primary objective of the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -1.00%)	✅ 100.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (a233ebc)	2441	2441	100.00%
Head commit (51b894c)	2445 (+4)	2445 (+4)	100.00% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#819)	4	4	100.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences