Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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.mdindex 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_statusReturn the effective Agent Evolution switch for the caller's account. ROOTdiff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex 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.mdindex 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.pyindex 8cb5dc627..0af056b73 100644--- a/openviking/server/account_stores/base.py+++ b/openviking/server/account_stores/base.py@@ -59,6 +59,18 @@ class AccountStore(ABC):@abstractmethodasync 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.pyindex 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.pyindex 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 summaryasync 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.pyindex 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.pyindex 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_rootasync 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_adminasync def get_user_settings(diff --git a/sdk/go/README.md b/sdk/go/README.mdindex 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.mdindex 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.goindex 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.goindex 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.mdindex 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.mdindex 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.pyindex 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.pyindex 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.asyncioasync 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.tsindex 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.tsindex 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.pyindex 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.textprobe.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()