Skip to content

feat: add optional per-key usage accounting and limits - #4753

Draft
xky-at-pku wants to merge 2 commits into
router-for-me:devfrom
xky-at-pku:agent/per-key-usage-limits
Draft

feat: add optional per-key usage accounting and limits#4753
xky-at-pku wants to merge 2 commits into
router-for-me:devfrom
xky-at-pku:agent/per-key-usage-limits

Conversation

@xky-at-pku

@xky-at-pku xky-at-pku commented Aug 3, 2026

Copy link
Copy Markdown

Summary

  • add optional named downstream API key profiles alongside the existing api-keys
  • persist per-key request and token usage in an embedded SQLite database
  • enforce weekly/monthly request and token limits plus case-insensitive model allowlists
  • expose authenticated Management API endpoints for profile CRUD, summaries, settings, and recent events
  • add operator documentation and a structured feature request template

Motivation

CLIProxyAPI intentionally removed built-in statistics in v6.10.0 and points billing-grade users to dedicated projects such as CPA Usage Keeper. Operators still need a lightweight local control for issuing one downstream key per person, seeing basic usage, and enforcing simple limits without running a separate analytics stack.

This implementation keeps that scope narrow and remains disabled by default.

Compatibility and security

  • existing api-keys continue to authenticate unchanged
  • accounting is opt-in through api-key-usage.enabled
  • generated keys use 32 random bytes (256 bits) and the full secret is returned only by the create response
  • list and update responses expose only a SHA-256 fingerprint
  • SQLite stores key hashes and aggregate usage; it does not store prompts, responses, or plaintext keys
  • request limits are reserved atomically before dispatch
  • token limits use completed usage, so a final concurrent response may slightly exceed the ceiling
  • CPA Usage Keeper remains the recommended option for billing-grade analytics and cost estimation

Validation

  • go test -p=1 ./...
  • server binary build through the cmd/server test/build path
  • focused tests for profile CRUD, key isolation, request/token limits, model allowlists, malformed/non-JSON bodies, canonical token accounting, persistence, and retention cleanup

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant