Skip to content

upstream-api-c2c19a7.md

Latest commit

 

History

History
51 lines (38 loc) · 4.39 KB

upstream-api-c2c19a7.md

File metadata and controls

51 lines (38 loc) · 4.39 KB
Raw

Upstream API baseline: c2c19a7

Compatibility is pinned to Wei-Shaw/sub2api commit c2c19a7cbe8486ebb5b56834d1a6e07b3f12cffc, whose server version is 0.1.159. The dashboard requires zero upstream source changes.

Calls used

Purpose Method and path Authentication
Public settings GET /api/v1/settings/public none
Login POST /api/v1/auth/login none
Two-factor login POST /api/v1/auth/login/2fa temporary token in request body
Refresh POST /api/v1/auth/refresh refresh token in request body
Current user GET /api/v1/auth/me Authorization: Bearer <user token>
Available groups GET /api/v1/groups/available Authorization: Bearer <user token>
Group account page GET /api/v1/admin/accounts?group=<id>&page=<n>&page_size=<n> x-api-key: <admin key>
Passive account usage GET /api/v1/admin/accounts/<id>/usage?source=passive x-api-key: <admin key>

There is no generic pass-through route. The dashboard does not call mutation, active test, billing, probe, forced refresh, or user-management endpoints.

Bootstrap and compliance

A new sub2api deployment must complete its own setup/bootstrap flow before this dashboard can work. Create or configure the upstream admin API key in upstream and provide it as SUB2API_ADMIN_API_KEY; the BFF sends it only as x-api-key on the two admin calls above.

An upstream HTTP 423 is surfaced as HTTP 423 with dashboard code COMPLIANCE_LOCKED. Complete the required upstream administrator compliance/setup action. The dashboard does not work around or auto-accept compliance.

Account and quota behavior

  • Admin account pages are requested for one allowlisted group and then defensively checked for group ownership.
  • Pagination accepts the pinned response conventions used by the BFF (items/accounts, pages/total_pages, and total) and is bounded locally.
  • Reaching MAX_PAGES or MAX_ACCOUNTS_PER_GROUP yields partial: true.
  • Passive usage is limited to Anthropic OAuth and SetupToken/setup-style credentials. The call always uses source=passive.
  • Lite/local accounts with no safe local quota fields cause no active upstream work; they remain unknown.
  • OpenAI OAuth accounts do not use the Anthropic passive endpoint. The BFF can map approved Codex 5-hour/7-day account snapshot fields from extra into local windows; 0% remains a known value. It prefers explicit reset timestamps, otherwise derives them from the usage update time plus reset-after seconds. Expired resets remain visible as stale utilization without resetsAt.
  • Other non-Anthropic accounts may use existing normalized top-level quota_* fields only. Unknown data remains unknown, never zero.
  • Account pagination is followed immediately by a whitelist normalization boundary, so account caches do not retain full extra, credentials, email, proxy, or cost fields.

Compatibility checks before changing the SHA

For every upstream upgrade, inspect the exact target commit and verify:

  1. Every path and HTTP method in the table still exists.
  2. User auth remains Bearer and admin auth remains x-api-key.
  3. Login 2FA still uses a non-empty temp_token and totp_code.
  4. Group availability and account membership fields retain compatible semantics.
  5. Pagination field names, termination behavior, and filters remain compatible.
  6. Passive usage still means no active request and still accepts source=passive for Anthropic OAuth/SetupToken.
  7. Compliance still returns 423 and has not introduced a required mutating acknowledgement.
  8. Response-size, timeout, and error behavior remain safely normalized.
  9. Contract, integration, E2E, lint, typecheck, build, and format checks all pass against a mock updated from the target SHA.

Record the new full SHA in CLAUDE.md, this document, and the README only after these checks. Do not track main implicitly.