[Feature] Add pagination support to `GET /v0/management/auth-files`

Author: seakeeCreated Sep 17, 2026Updated Sep 17, 2026
LabelsFixed

Background

GET /v0/management/auth-files currently returns the complete auth credential list.

This becomes expensive for large credential pools containing thousands of accounts. Downstream management UIs may display only 10–50 credentials per page, but they still need to download and process the entire credential list for every full refresh.

A real-world example was reported in CPA Manager Plus:

https://github.com/seakee/CPA-Manager-Plus/issues/804

With several thousand credentials, opening the credential management page can take a noticeable amount of time because the full /auth-files response must be fetched even when the UI only displays a small page.

Current behavior

The endpoint currently supports identity filtering such as:

GET /v0/management/auth-files?name=xxx
GET /v0/management/auth-files?name=xxx&auth_index=xxx

However, there is currently no pagination mechanism for normal credential-list queries.

Requested capability

Please add optional server-side pagination support to:

GET /v0/management/auth-files

For example:

GET /v0/management/auth-files?page=1&page_size=50

The exact parameter naming can follow the project's preferred API convention.

The paginated response should ideally expose enough metadata for management clients to render pagination, for example:

{
  "observed_at": "...",
  "files": [],
  "total": 5000,
  "page": 1,
  "page_size": 50
}

has_more may also be useful, but is not required if total is available.

Compatibility

Please preserve the existing behavior when pagination parameters are omitted:

GET /v0/management/auth-files

should continue returning the complete list so existing management clients remain compatible.

Existing name / auth_index lookup behavior should also remain unchanged.

Pagination semantics

To keep page contents deterministic:

  1. Apply the existing credential visibility/filtering rules.
  2. Apply the existing stable ordering.
  3. Calculate the total matching count.
  4. Apply pagination to the ordered result.

This avoids credentials moving unpredictably between pages.

The same behavior should ideally apply whether credentials are served from the runtime auth manager or the disk fallback path.

Expected result

For a pool containing several thousand credentials, a management client should be able to request only the credentials required for the current page instead of transferring and serializing the entire credential pool.

Example:

GET /v0/management/auth-files?page=1&page_size=10

should return approximately 10 credential entries plus pagination metadata, rather than the complete credential list.

Motivation

This is mainly intended for management interfaces and other downstream tools operating large credential pools.

Server-side pagination would significantly reduce:

  • response payload size
  • JSON serialization/deserialization cost
  • network transfer
  • frontend memory usage
  • full-list processing during normal page navigation

while keeping the existing unpaginated API backward-compatible.

Source: router-for-me/CLIProxyAPI