steipete--codexbar/docs/sub2api.md

summary, read_when

summary	read_when
sub2api setup for group API-key quota, subscription usage, and wallet balance.	Configuring sub2api usage tracking Monitoring multiple sub2api groups Troubleshooting the sub2api /v1/usage integration

sub2api

CodexBar reads the accounting data exposed by a sub2api group API key. It calls only GET /v1/usage; it does not send model requests, read prompts, or require a dashboard JWT.

Setup

Configure the deployment URL in Settings → Providers → sub2api. The URL must use HTTPS, except for loopback HTTP such as http://127.0.0.1:8080 during local development.

For one group, paste its key into the fallback API key field or configure environment variables:

export SUB2API_BASE_URL=https://sub2api.example.com
export SUB2API_API_KEY=sk-...

For multiple groups, create one key per group in sub2api, then add each key under Group API keys with a descriptive label such as Claude, Codex, or Gemini. CodexBar's account switcher selects the active key; stacked account mode can fetch and display several group keys at once.

Display

The response mode determines what CodexBar shows:

• Quota-limited key: total quota plus optional 5-hour, daily, and 7-day rate-limit windows.
• Subscription group: daily, weekly, and monthly spend against configured limits, plus expiration.
• Wallet group: current wallet balance.
• All modes: today and total key-scoped requests, tokens, and actual cost when sub2api returns them.

Usage totals are scoped to the authenticated key. Wallet balance is scoped to the owning user, so CodexBar keeps it on each account card and does not sum it across keys.

For subscription groups, CodexBar displays the daily, weekly, and monthly counters returned by /v1/usage. These windows follow the subscription's billing anchors; the endpoint does not expose enough boundary information to reconstruct them safely from the key-scoped calendar-day series. If several keys share one group, the subscription counters can therefore be shared even though the request and cost totals remain key-scoped.

Security

Keys are stored using CodexBar's existing provider config or token-account storage. CodexBar sends a key only to the validated base URL using Authorization: Bearer <key>.