Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(admin): O(1) account/user existence endpoints (#6325)

nocvalight102ff5925665
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index 498315735..64aad1ced 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -506,9 +506,11 @@ This catalog follows the routes actually mounted by the server. Each group headi
| POST | `/api/v1/admin/accounts` | Create an account and its first administrator |
| GET | `/api/v1/admin/accounts` | List accounts |
| POST | `/api/v1/admin/migrate` | Migrate legacy identity data |
+| GET | `/api/v1/admin/accounts/{account_id}` | Get credential-free metadata for one account |
| DELETE | `/api/v1/admin/accounts/{account_id}` | Delete an account |
| POST | `/api/v1/admin/accounts/{account_id}/users` | Register a user |
| GET | `/api/v1/admin/accounts/{account_id}/users` | List users |
+| GET | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | Get one user's credential-free membership info (user_id, role) |
| GET | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | Get a user's memory policy |
| PATCH | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | Update a user's memory policy |
| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | Remove a user |
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index 048fb90ee..e254c2fa6 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -85,6 +85,66 @@ The Python SDK exposes `admin_create_group`, `admin_list_groups`, `admin_list_gr
## API Reference
+### account / user existence queries
+
+Before creating an Account/User, use these exact existence probes instead of
+"list then compare locally". Both hit the in-memory registry in O(1) and return
+only credential-free information. With `server.api_key_watch_enabled` enabled
+they read memory directly; otherwise they fall back to reading the persisted
+registry.
+
+**Fetch one Account (ROOT only)**
+
+```
+GET /api/v1/admin/accounts/{account_id}
+```
+
+Returns the account's credential-free metadata on hit, or 404 if absent.
+
+```bash
+curl "http://localhost:1933/api/v1/admin/accounts/team-a" \
+ -H "X-API-Key: <root-key>"
+```
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "account_id": "team-a",
+ "created_at": "2026-10-20T03:00:00Z",
+ "user_count": 2,
+ "status": "active"
+ }
+}
+```
+
+When `status` is `deleting`, a `task_id` is included. The response never
+contains `api_key`, `user_key`, `key_prefix`, or `seed`.
+
+**Get one user's membership info (ROOT or the account's ADMIN)**
+
+```
+GET /api/v1/admin/accounts/{account_id}/users/{user_id}
+```
+
+Point-reads a single user and returns only credential-free membership info,
+deliberately not reusing any user-read shape that could return credentials:
+
+```bash
+curl "http://localhost:1933/api/v1/admin/accounts/team-a/users/alice" \
+ -H "X-API-Key: <root-key>"
+```
+
+```json
+{ "status": "ok", "result": { "user_id": "alice", "role": "admin" } }
+```
+
+The response contains only `user_id` and `role`; it never includes `api_key`
+or `key_prefix`. A missing user returns 404. An ADMIN may only query its own
+account; cross-account access returns 403. This can back a pre-create check;
+concurrent uniqueness is still guaranteed by the create-time write conflict
+(`ALREADY_EXISTS`).
+
### get_agent_evolution_status
Return the effective Agent Evolution switch for the caller's account. ROOT
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index e32022509..5a8715359 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -501,9 +501,11 @@ JSON 输出 - 错误:
| POST | `/api/v1/admin/accounts` | 创建账号及首个管理员 |
| GET | `/api/v1/admin/accounts` | 列出账号 |
| POST | `/api/v1/admin/migrate` | 迁移旧版身份数据 |
+| GET | `/api/v1/admin/accounts/{account_id}` | 获取单个账号的无凭据元数据 |
| DELETE | `/api/v1/admin/accounts/{account_id}` | 删除账号 |
| POST | `/api/v1/admin/accounts/{account_id}/users` | 注册用户 |
| GET | `/api/v1/admin/accounts/{account_id}/users` | 列出用户 |
+| GET | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | 获取单个用户的无凭据成员信息(user_id、role) |
| GET | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | 获取用户记忆策略 |
| PATCH | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | 更新用户记忆策略 |
| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | 移除用户 |
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index 3e3d22248..5fbd0a81f 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -85,6 +85,56 @@ Python SDK 提供对应的 `admin_create_group`、`admin_list_groups`、`admin_l
## API 参考
+### account / user 存在性查询
+
+创建 Account/User 前可用两个精确判存接口替代“列出后本地比对”。二者都命中内存注册表,时间复杂度 O(1),且只返回无凭据信息;开启 `server.api_key_watch_enabled` 时直接读内存,关闭时会回退读取持久化的注册表。
+
+**查询单个 Account(仅 ROOT)**
+
+```
+GET /api/v1/admin/accounts/{account_id}
+```
+
+命中返回该 Account 的无凭据元数据;不存在返回 404。
+
+```bash
+curl "http://localhost:1933/api/v1/admin/accounts/team-a" \
+ -H "X-API-Key: <root-key>"
+```
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "account_id": "team-a",
+ "created_at": "2026-10-20T03:00:00Z",
+ "user_count": 2,
+ "status": "active"
+ }
+}
+```
+
+`status` 为 `deleting` 时附带 `task_id`。响应不包含 `api_key`、`user_key`、`key_prefix` 或 `seed`。
+
+**查询单个 User 的成员信息(ROOT 或本 Account 的 ADMIN)**
+
+```
+GET /api/v1/admin/accounts/{account_id}/users/{user_id}
+```
+
+点读单个用户,仅返回无凭据的成员信息,刻意不复用任何会返回凭据的 user 读取形态:
+
+```bash
+curl "http://localhost:1933/api/v1/admin/accounts/team-a/users/alice" \
+ -H "X-API-Key: <root-key>"
+```
+
+```json
+{ "status": "ok", "result": { "user_id": "alice", "role": "admin" } }
+```
+
+返回仅含 `user_id` 与 `role`,**不包含** `api_key` 或 `key_prefix`。用户不存在返回 404。ADMIN 只能查询自己所属的 Account,跨 Account 返回 403。创建前的判重可据此进行;并发唯一性仍由创建时的写入冲突(`ALREADY_EXISTS`)兜底。
+
### get_agent_evolution_status
返回调用方所属 account 的 Agent 进化实时状态。ROOT 操作已配置的默认
diff --git a/openviking/server/account_stores/base.py b/openviking/server/account_stores/base.py
index 8cb5dc627..0af056b73 100644
--- a/openviking/server/account_stores/base.py
+++ b/openviking/server/account_stores/base.py
@@ -59,6 +59,18 @@ class AccountStore(ABC):
@abstractmethod
async def get_user(self, account_id: str, user_id: str) -> UserSummary | None: ...
+ async def get_user_membership(
+ self, account_id: str, user_id: str
+ ) -> UserSummary | None:
+ """Point-read one user for the admin membership probe.
+
+ Mirrors ``get_account``: stores whose in-memory state can lag a peer
+ process (FileStore with the watcher off) override this to refresh from
+ the persisted registry first. Query-per-call stores (MySQL) are always
+ fresh and keep the default delegation.
+ """
+ return await self.get_user(account_id, user_id)
+
@deprecated(
"get_user_for_management is a FileStore compatibility path and will be removed.",
category=None,
diff --git a/openviking/server/account_stores/redis_mysql.py b/openviking/server/account_stores/redis_mysql.py
index d830a3091..8827b4424 100644
--- a/openviking/server/account_stores/redis_mysql.py
+++ b/openviking/server/account_stores/redis_mysql.py
@@ -724,6 +724,13 @@ class RedisMySQLAccountStore(AccountStore):
)
return value if value is None else UserSummary(value)
+ async def get_user_membership(
+ self, account_id: str, user_id: str
+ ) -> UserSummary | None:
+ # Bypass the read-through cache: the admin membership probe must reflect
+ # the latest persisted state, which MySQL indexes directly.
+ return await self._mysql.get_user_membership(account_id, user_id)
+
async def get_user_group_ids(self, account_id: str, user_id: str) -> tuple[str, ...]:
value = await self._read_through(
account_id,
diff --git a/openviking/server/api_keys/legacy.py b/openviking/server/api_keys/legacy.py
index 112b844fc..34addea88 100644
--- a/openviking/server/api_keys/legacy.py
+++ b/openviking/server/api_keys/legacy.py
@@ -969,15 +969,9 @@ class FileStore(AccountStore):
if query and query not in account_id.casefold():
continue
- result.append(
- {
- "account_id": account_id,
- "created_at": info.created_at,
- "user_count": len(info.users),
- "status": "deleting" if info.deletion else "active",
- **({"task_id": info.deletion["task_id"]} if info.deletion else {}),
- }
- )
+ # Reuse the single-account summary builder so the listed shape and
+ # the point-read stay one maintenance point.
+ result.append(self._account_summary(account_id, info))
return _paginate(result, limit, page)
def _get_users(
@@ -1453,14 +1447,22 @@ class FileStore(AccountStore):
async def get_account(self, account_id: str) -> AccountSummary | None:
await self._refresh_accounts_for_management_read()
- return next(
- (
- account
- for account in self._get_accounts()
- if account["account_id"] == account_id
- ),
- None,
- )
+ info = self._accounts.get(account_id)
+ if info is None:
+ return None
+ return self._account_summary(account_id, info)
+
+ def _account_summary(self, account_id: str, info: AccountInfo) -> AccountSummary:
+ """Credential-free metadata for one in-memory account (O(1))."""
+ summary: AccountSummary = {
+ "account_id": account_id,
+ "created_at": info.created_at,
+ "user_count": len(info.users),
+ "status": "deleting" if info.deletion else "active",
+ }
+ if info.deletion:
+ summary["task_id"] = info.deletion["task_id"]
+ return summary
async def get_user(self, account_id: str, user_id: str) -> UserSummary | None:
account = self._accounts.get(account_id)
@@ -1473,6 +1475,22 @@ class FileStore(AccountStore):
else None
)
+ async def get_user_membership(
+ self, account_id: str, user_id: str
+ ) -> UserSummary | None:
+ """Refresh-first point read, symmetric with ``get_account``.
+
+ The hot-path ``get_user`` reads in-memory state directly; this admin
+ probe first honors the persisted registry when the watcher is off, so a
+ user created or re-roled by a peer process is visible cross-instance
+ instead of returning a stale 404 or role. Mirrors
+ ``list_users_page(fresh=False)``: the refresh raises
+ ``NotFoundError(account)`` for an unknown account and that bubbles up as
+ a 404, matching the list endpoint.
+ """
+ await self._refresh_users_for_management_read(account_id)
+ return await self.get_user(account_id, user_id)
+
@deprecated(
"get_user_for_management is a FileStore compatibility path and will be removed.",
category=None,
diff --git a/openviking/server/api_keys/new.py b/openviking/server/api_keys/new.py
index fc3fbdcc2..f7c6e0db1 100644
--- a/openviking/server/api_keys/new.py
+++ b/openviking/server/api_keys/new.py
@@ -218,6 +218,9 @@ class APIKeyManager:
async def get_user(self, account_id, user_id):
return await self._store.get_user(account_id, user_id)
+ async def get_user_membership(self, account_id, user_id):
+ return await self._store.get_user_membership(account_id, user_id)
+
@deprecated(
"get_user_for_management is a FileStore compatibility path and will be removed.",
category=None,
diff --git a/openviking/server/routers/admin.py b/openviking/server/routers/admin.py
index 3993c9f14..5569c24fe 100644
--- a/openviking/server/routers/admin.py
+++ b/openviking/server/routers/admin.py
@@ -521,6 +521,20 @@ async def list_accounts(
return Response(status="ok", result=accounts)
[email protected]("/accounts/{account_id}")
+@require_auth_root
+async def get_account(
+ request: Request,
+ account_id: str,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Return credential-free metadata for one account, or 404 if absent."""
+ account = await _get_api_key_manager(request).get_account(account_id)
+ if account is None:
+ raise NotFoundError(account_id, "account")
+ return Response(status="ok", result=account)
+
+
@router.post("/migrate")
@require_auth_root
async def migrate_legacy_data(
@@ -1036,6 +1050,26 @@ async def list_users(
return Response(status="ok", result=users if include_summary else users["users"])
[email protected]("/accounts/{account_id}/users/{user_id}")
+@require_auth_root_or_admin
+async def get_user(
+ request: Request,
+ account_id: str = Path(..., description="Account ID"),
+ user_id: str = Path(..., description="User ID"),
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Return one user's credential-free membership info, or 404 if absent.
+
+ Deliberately returns only ``user_id`` and ``role``; it never exposes
+ ``api_key`` or ``key_prefix``.
+ """
+ _check_account_access(ctx, account_id)
+ user = await _get_api_key_manager(request).get_user_membership(account_id, user_id)
+ if user is None:
+ raise NotFoundError(user_id, "user")
+ return Response(status="ok", result={"user_id": user_id, "role": user["role"]})
+
+
@router.get("/accounts/{account_id}/users/{user_id}/settings")
@require_auth_root_or_admin
async def get_user_settings(
diff --git a/sdk/go/README.md b/sdk/go/README.md
index 1eb0f8dc2..0ee4ed1ac 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -174,7 +174,7 @@ Implemented:
| Sessions and tasks | `CreateSession`, `ListSessions`, `GetSession`, `UpdateSessionConfig`, `SessionExists`, `GetSessionContext`, `GetSessionArchive`, `DeleteSession`, `AddMessage`, `BatchAddMessages`, `CommitSession`, `GetTask`, `ListTasks` |
| Packs | `ExportOVPack`, `BackupOVPack`, `ImportOVPack`, `RestoreOVPack` |
| System and observer | `Health`, `CheckConsistency`, `GetStatus`, `IsHealthy`, `QueueStatus`, `VikingDBStatus`, `ModelsStatus` |
-| Admin | `AdminCreateAccount`, `AdminCreateAccountWithOptions`, `AdminListAccounts`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminRegisterUserWithOptions`, `AdminListUsers`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminRegenerateKeyWithOptions`, `AdminMigrate` |
+| Admin | `AdminCreateAccount`, `AdminCreateAccountWithOptions`, `AdminListAccounts`, `AdminGetAccount`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminRegisterUserWithOptions`, `AdminListUsers`, `AdminGetUser`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminRegenerateKeyWithOptions`, `AdminMigrate` |
Not implemented in Go SDK v1:
diff --git a/sdk/go/README_CN.md b/sdk/go/README_CN.md
index 526e8bf2b..bba7a0d3e 100644
--- a/sdk/go/README_CN.md
+++ b/sdk/go/README_CN.md
@@ -73,7 +73,7 @@ _, _, _ = imageResults, storedImageResults, similarPosters
| 会话和任务 | `CreateSession`, `ListSessions`, `GetSession`, `UpdateSessionConfig`, `SessionExists`, `GetSessionContext`, `GetSessionArchive`, `DeleteSession`, `AddMessage`, `BatchAddMessages`, `CommitSession`, `GetTask`, `ListTasks` |
| OVPack | `ExportOVPack`, `BackupOVPack`, `ImportOVPack`, `RestoreOVPack` |
| 系统和 observer | `Health`, `CheckConsistency`, `GetStatus`, `IsHealthy`, `QueueStatus`, `VikingDBStatus`, `ModelsStatus` |
-| 管理接口 | `AdminCreateAccount`, `AdminCreateAccountWithOptions`, `AdminListAccounts`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminRegisterUserWithOptions`, `AdminListUsers`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminRegenerateKeyWithOptions`, `AdminMigrate` |
+| 管理接口 | `AdminCreateAccount`, `AdminCreateAccountWithOptions`, `AdminListAccounts`, `AdminGetAccount`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminRegisterUserWithOptions`, `AdminListUsers`, `AdminGetUser`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminRegenerateKeyWithOptions`, `AdminMigrate` |
## 暂未实现接口
diff --git a/sdk/go/admin.go b/sdk/go/admin.go
index 0c07bc469..3c5c56a33 100644
--- a/sdk/go/admin.go
+++ b/sdk/go/admin.go
@@ -63,6 +63,25 @@ func (c *Client) AdminDeleteAccount(ctx context.Context, accountID string) (map[
return result, err
}
+// AdminGetAccount returns credential-free metadata for one account.
+// It returns an *Error with code NOT_FOUND when the account does not exist.
+func (c *Client) AdminGetAccount(ctx context.Context, accountID string) (map[string]any, error) {
+ var result map[string]any
+ err := c.doJSON(ctx, http.MethodGet, "/api/v1/admin/accounts/"+url.PathEscape(accountID), nil, nil, &result)
+ return result, err
+}
+
+// AdminGetUser returns one user's credential-free membership info (user_id, role).
+// It returns an *Error with code NOT_FOUND when the user does not exist and never
+// exposes api_key or key_prefix.
+func (c *Client) AdminGetUser(ctx context.Context, accountID, userID string) (map[string]any, error) {
+ var result map[string]any
+ path := "/api/v1/admin/accounts/" + url.PathEscape(accountID) +
+ "/users/" + url.PathEscape(userID)
+ err := c.doJSON(ctx, http.MethodGet, path, nil, nil, &result)
+ return result, err
+}
+
// AdminRegisterUser registers a user in an account.
func (c *Client) AdminRegisterUser(ctx context.Context, accountID, userID, role string) (map[string]any, error) {
return c.AdminRegisterUserWithOptions(ctx, accountID, userID, role, nil)
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index b22f3429d..d7cd3d5aa 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -647,6 +647,86 @@ func TestAdminEmptySeedPayloadsAreSent(t *testing.T) {
}
}
+func TestAdminGetAccount(t *testing.T) {
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ t.Fatalf("method = %s", r.Method)
+ }
+ if r.URL.Path != "/api/v1/admin/accounts/acct" {
+ t.Fatalf("path = %s", r.URL.Path)
+ }
+ writeOK(t, w, map[string]any{
+ "account_id": "acct",
+ "created_at": "2026-10-20T03:00:00Z",
+ "user_count": 2,
+ "status": "active",
+ })
+ }))
+ defer closeServer()
+
+ account, err := client.AdminGetAccount(context.Background(), "acct")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if account["status"] != "active" || account["user_count"] != float64(2) {
+ t.Fatalf("account = %#v", account)
+ }
+ if _, ok := account["api_key"]; ok {
+ t.Fatal("account metadata must not include credentials")
+ }
+}
+
+func TestAdminGetAccountNotFound(t *testing.T) {
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ writeAPIError(t, w, http.StatusNotFound, "NOT_FOUND", nil)
+ }))
+ defer closeServer()
+
+ if _, err := client.AdminGetAccount(context.Background(), "missing"); !IsCode(err, "NOT_FOUND") {
+ t.Fatalf("err = %v, want NOT_FOUND", err)
+ }
+}
+
+func TestAdminGetUser(t *testing.T) {
+ var requestedPath string
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ t.Fatalf("method = %s", r.Method)
+ }
+ requestedPath = r.URL.Path
+ writeOK(t, w, map[string]any{"user_id": "alice", "role": "admin"})
+ }))
+ defer closeServer()
+
+ user, err := client.AdminGetUser(context.Background(), "acct", "alice")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if user["user_id"] != "alice" || user["role"] != "admin" {
+ t.Fatalf("user = %#v", user)
+ }
+ if _, ok := user["api_key"]; ok {
+ t.Fatal("user membership must not include credentials")
+ }
+ if _, ok := user["key_prefix"]; ok {
+ t.Fatal("user membership must not include credentials")
+ }
+ if requestedPath != "/api/v1/admin/accounts/acct/users/alice" {
+ t.Fatalf("path = %s", requestedPath)
+ }
+}
+
+func TestAdminGetUserNotFound(t *testing.T) {
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ writeAPIError(t, w, http.StatusNotFound, "NOT_FOUND", nil)
+ }))
+ defer closeServer()
+
+ if _, err := client.AdminGetUser(context.Background(), "acct", "ghost"); !IsCode(err, "NOT_FOUND") {
+ t.Fatalf("err = %v, want NOT_FOUND", err)
+ }
+}
+
func TestSearchSendsSessionAndSearchFilters(t *testing.T) {
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/api/v1/search/search" {
diff --git a/sdk/python/README.md b/sdk/python/README.md
index fcbd7ae18..dd2f7f371 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -331,7 +331,9 @@ If you connect with a root key, the SDK also exposes admin APIs such as:
- `admin_create_account`
- `admin_register_user`
- `admin_list_accounts`
+- `admin_get_account`
- `admin_list_users`
+- `admin_get_user`
- `admin_regenerate_key`
- `admin_delete_account`
diff --git a/sdk/python/README_CN.md b/sdk/python/README_CN.md
index 8d7d59945..7584707bc 100644
--- a/sdk/python/README_CN.md
+++ b/sdk/python/README_CN.md
@@ -319,7 +319,9 @@ result = client.find(
- `admin_create_account`
- `admin_register_user`
- `admin_list_accounts`
+- `admin_get_account`
- `admin_list_users`
+- `admin_get_user`
- `admin_regenerate_key`
- `admin_delete_account`
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index a6ca49014..2103e44e6 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -1947,6 +1947,14 @@ class AsyncHTTPClient:
response = await self._request("GET", "/api/v1/admin/accounts", params=params)
return self._handle_response(response)
+ async def admin_get_account(self, account_id: str) -> Dict[str, Any]:
+ """Return one account's credential-free metadata.
+
+ Raises NotFoundError when the account does not exist.
+ """
+ response = await self._request("GET", f"/api/v1/admin/accounts/{account_id}")
+ return self._handle_response(response)
+
async def admin_delete_account(self, account_id: str) -> Dict[str, Any]:
response = await self._request("DELETE", f"/api/v1/admin/accounts/{account_id}")
return self._handle_response(response)
@@ -1995,6 +2003,18 @@ class AsyncHTTPClient:
)
return self._handle_response(response)
+ async def admin_get_user(self, account_id: str, user_id: str) -> Dict[str, Any]:
+ """Return one user's credential-free membership info (user_id, role).
+
+ Raises NotFoundError when the user does not exist. Never returns
+ api_key or key_prefix.
+ """
+ response = await self._request(
+ "GET",
+ f"/api/v1/admin/accounts/{account_id}/users/{user_id}",
+ )
+ return self._handle_response(response)
+
async def admin_remove_user(self, account_id: str, user_id: str) -> Dict[str, Any]:
response = await self._request(
"DELETE", f"/api/v1/admin/accounts/{account_id}/users/{user_id}"
@@ -3057,6 +3077,9 @@ class SyncHTTPClient:
def admin_delete_account(self, account_id: str) -> Dict[str, Any]:
return run_async(self._async_client.admin_delete_account(account_id))
+ def admin_get_account(self, account_id: str) -> Dict[str, Any]:
+ return run_async(self._async_client.admin_get_account(account_id))
+
def admin_register_user(
self,
account_id: str,
@@ -3093,6 +3116,9 @@ class SyncHTTPClient:
def admin_remove_user(self, account_id: str, user_id: str) -> Dict[str, Any]:
return run_async(self._async_client.admin_remove_user(account_id, user_id))
+ def admin_get_user(self, account_id: str, user_id: str) -> Dict[str, Any]:
+ return run_async(self._async_client.admin_get_user(account_id, user_id))
+
def admin_set_role(self, account_id: str, user_id: str, role: str) -> Dict[str, Any]:
return run_async(self._async_client.admin_set_role(account_id, user_id, role))
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index aca3532f4..3c75a560f 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -654,6 +654,8 @@ def test_sync_http_client_declares_common_sync_methods_explicitly():
"get_task",
"list_tasks",
"admin_list_accounts",
+ "admin_get_account",
+ "admin_get_user",
]:
assert method_name in explicit_methods, method_name
@@ -1190,6 +1192,37 @@ async def test_admin_seed_payloads_are_sent():
assert fake_http.post.await_args_list[2].kwargs["json"] == {"seed": "new-seed"}
+async def test_admin_get_account_uses_exact_path_and_returns_metadata():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ client._request = AsyncMock(return_value=object())
+ client._handle_response = lambda _response: {
+ "account_id": "acct",
+ "status": "active",
+ "user_count": 2,
+ }
+
+ result = await client.admin_get_account("acct")
+
+ client._request.assert_awaited_once_with("GET", "/api/v1/admin/accounts/acct")
+ assert result["user_count"] == 2
+ assert "api_key" not in result
+
+
+async def test_admin_get_user_reads_membership_from_point_read_path():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ client._request = AsyncMock(return_value=object())
+ client._handle_response = lambda _response: {"user_id": "alice", "role": "admin"}
+
+ result = await client.admin_get_user("acct", "alice")
+ client._request.assert_awaited_once_with(
+ "GET", "/api/v1/admin/accounts/acct/users/alice"
+ )
+ assert result == {"user_id": "alice", "role": "admin"}
+ assert "api_key" not in result and "key_prefix" not in result
+
+
@pytest.mark.asyncio
async def test_import_ovpack_uploads_local_file_even_when_url_is_localhost(tmp_path):
pack_file = tmp_path / "demo.ovpack"
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index 3447a891c..3876e9921 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -1249,6 +1249,10 @@ export class OpenVikingClient {
`/api/v1/admin/accounts/${pathPart(accountId)}`,
);
}
+ /** Return credential-free metadata for one account; rejects with NOT_FOUND if absent. */
+ adminGetAccount(accountId: string): Promise<JsonObject> {
+ return this.request("GET", `/api/v1/admin/accounts/${pathPart(accountId)}`);
+ }
/** Register a user in an account. */
adminRegisterUser(
accountId: string,
@@ -1299,6 +1303,13 @@ export class OpenVikingClient {
`/api/v1/admin/accounts/${pathPart(accountId)}/users/${pathPart(userId)}`,
);
}
+ /** One user's credential-free membership info (user_id, role); rejects NOT_FOUND if absent. Never returns api_key/key_prefix. */
+ adminGetUser(accountId: string, userId: string): Promise<JsonObject> {
+ return this.request(
+ "GET",
+ `/api/v1/admin/accounts/${pathPart(accountId)}/users/${pathPart(userId)}`,
+ );
+ }
/** Change a user's role. */
adminSetRole(
accountId: string,
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index 6e57cab77..ffbbb0eed 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -1477,4 +1477,49 @@ describe("OpenVikingClient", () => {
content: "*.log\n",
});
});
+
+ it("fetches one account by exact path without leaking credentials", async () => {
+ const fetcher = vi.fn<typeof fetch>().mockResolvedValue(
+ ok({
+ account_id: "team-a",
+ created_at: "2026-10-20T03:00:00Z",
+ user_count: 2,
+ status: "active",
+ }),
+ );
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ apiKey: "root-key",
+ fetch: fetcher,
+ });
+
+ const account = await client.adminGetAccount("team-a");
+ expect(account).toMatchObject({ account_id: "team-a", status: "active" });
+ expect(account).not.toHaveProperty("api_key");
+
+ const url = new URL(String(fetcher.mock.calls[0]![0]));
+ expect(url.pathname).toBe("/api/v1/admin/accounts/team-a");
+ expect(
+ new Headers(fetcher.mock.calls[0]![1]?.headers).get("X-API-Key"),
+ ).toBe("root-key");
+ });
+
+ it("reads one user's membership by exact path without leaking credentials", async () => {
+ const fetcher = vi
+ .fn<typeof fetch>()
+ .mockResolvedValue(ok({ user_id: "alice", role: "admin" }));
+ const client = new OpenVikingClient({
+ baseUrl: "https://example.com",
+ apiKey: "root-key",
+ fetch: fetcher,
+ });
+
+ const user = await client.adminGetUser("team-a", "alice");
+ expect(user).toEqual({ user_id: "alice", role: "admin" });
+ expect(user).not.toHaveProperty("api_key");
+ expect(user).not.toHaveProperty("key_prefix");
+
+ const url = new URL(String(fetcher.mock.calls[0]![0]));
+ expect(url.pathname).toBe("/api/v1/admin/accounts/team-a/users/alice");
+ });
});
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 4bd89262c..38fb90412 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -3717,3 +3717,172 @@ async def test_private_model_probe_passes_draft_without_saving(
assert response.json()["result"] == {"ok": True, "ms": 12}
assert "draft-secret" not in response.text
probe.assert_awaited_once_with("vlm", body["config"], body["fallback"], True, "dense")
+
+
+# ---- Exact account/user existence probes ----
+
+
+async def test_get_account_returns_credential_free_metadata_or_404(
+ lightweight_admin_client,
+):
+ account_id = _uid()
+ missing = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{account_id}", headers=root_headers()
+ )
+ assert missing.status_code == 404
+
+ created = await lightweight_admin_client.post(
+ "/api/v1/admin/accounts",
+ json={"account_id": account_id, "admin_user_id": "alice"},
+ headers=root_headers(),
+ )
+ assert created.status_code == 200
+
+ response = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{account_id}", headers=root_headers()
+ )
+ assert response.status_code == 200, response.text
+ result = response.json()["result"]
+ assert result == {
+ "account_id": account_id,
+ "created_at": result["created_at"],
+ "user_count": 1,
+ "status": "active",
+ }
+ # Existence metadata must never carry credentials.
+ body = response.text
+ for secret_field in ("api_key", "user_key", "key_prefix", "seed"):
+ assert secret_field not in body
+
+
+async def test_get_account_is_root_only(template_account, lightweight_admin_client):
+ account_id, admin_headers = template_account
+ response = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{account_id}", headers=admin_headers
+ )
+ assert response.status_code == 403
+
+
+async def test_user_point_read_returns_role_without_credentials(
+ lightweight_admin_client,
+):
+ account_id = _uid()
+ created = await lightweight_admin_client.post(
+ "/api/v1/admin/accounts",
+ json={"account_id": account_id, "admin_user_id": "alice"},
+ headers=root_headers(),
+ )
+ assert created.status_code == 200
+ admin_headers = {"X-API-Key": created.json()["result"]["user_key"]}
+
+ registered = await lightweight_admin_client.post(
+ f"/api/v1/admin/accounts/{account_id}/users",
+ json={"user_id": "bob"},
+ headers=admin_headers,
+ )
+ assert registered.status_code == 200
+
+ for user_id, role in (("alice", "admin"), ("bob", "user")):
+ response = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{account_id}/users/{user_id}",
+ headers=root_headers(),
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["result"] == {"user_id": user_id, "role": role}
+ # The point read is defined as a credential-free membership probe; weld
+ # that contract shut so no credential field can ever leak through it.
+ for secret_field in ("api_key", "user_key", "key_prefix", "seed"):
+ assert secret_field not in response.text
+
+ unknown_user = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{account_id}/users/ghost",
+ headers=root_headers(),
+ )
+ assert unknown_user.status_code == 404
+ assert unknown_user.json()["error"]["message"] == "User not found: ghost"
+
+ # An unknown account bubbles up the account-level 404 from the refresh,
+ # matching list_users rather than masquerading as a missing user.
+ unknown_account_id = _uid()
+ unknown_account = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{unknown_account_id}/users/alice",
+ headers=root_headers(),
+ )
+ assert unknown_account.status_code == 404
+ assert (
+ unknown_account.json()["error"]["message"]
+ == f"Account not found: {unknown_account_id}"
+ )
+
+
+async def test_user_point_read_admin_scoped_to_own_account(lightweight_admin_client):
+ account_id = _uid()
+ other = _uid()
+ created = await lightweight_admin_client.post(
+ "/api/v1/admin/accounts",
+ json={"account_id": account_id, "admin_user_id": "alice"},
+ headers=root_headers(),
+ )
+ admin_headers = {"X-API-Key": created.json()["result"]["user_key"]}
+ await lightweight_admin_client.post(
+ "/api/v1/admin/accounts",
+ json={"account_id": other, "admin_user_id": "alice"},
+ headers=root_headers(),
+ )
+
+ own = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{account_id}/users/alice",
+ headers=admin_headers,
+ )
+ assert own.status_code == 200
+ assert own.json()["result"] == {"user_id": "alice", "role": "admin"}
+
+ denied = await lightweight_admin_client.get(
+ f"/api/v1/admin/accounts/{other}/users/alice",
+ headers=admin_headers,
+ )
+ assert denied.status_code == 403
+
+
+async def test_user_point_read_sees_peer_process_writes_without_a_list(
+ admin_client: httpx.AsyncClient,
+ admin_app: FastAPI,
+ admin_service: OpenVikingService,
+):
+ """Point read must not depend on a preceding list to refresh the registry.
+
+ With the account-store watcher off (the default), a user created or re-roled
+ by a peer process landed in the shared store but not in this instance's
+ memory. The membership probe refreshes on demand, so it must not return a
+ stale 404 or a stale role.
+ """
+ writer = build_api_key_manager(
+ root_key=ROOT_KEY,
+ viking_fs=admin_service.viking_fs,
+ )
+ await writer.load()
+ try:
+ acct = _uid()
+ await writer.create_account(acct, "alice")
+ await writer.register_user(acct, "bob", role="user")
+
+ # The serving instance never listed this account, so bob is only in the
+ # peer's store. The probe must still resolve him.
+ created = await admin_client.get(
+ f"/api/v1/admin/accounts/{acct}/users/bob",
+ headers=root_headers(),
+ )
+ assert created.status_code == 200, created.text
+ assert created.json()["result"] == {"user_id": "bob", "role": "user"}
+
+ # A peer-side role change must be reflected too, not served from stale
+ # memory.
+ await writer.set_role(acct, "bob", "admin")
+ rerole = await admin_client.get(
+ f"/api/v1/admin/accounts/{acct}/users/bob",
+ headers=root_headers(),
+ )
+ assert rerole.status_code == 200, rerole.text
+ assert rerole.json()["result"] == {"user_id": "bob", "role": "admin"}
+ finally:
+ await writer.close()