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
docs: clarify user_key vs root_key in quickstart and basic usage (#1077)
r266-techb95582111606
diff --git a/docs/en/getting-started/03-quickstart-server.md b/docs/en/getting-started/03-quickstart-server.mdindex 6fb49012a..8396280a9 100644--- a/docs/en/getting-started/03-quickstart-server.md+++ b/docs/en/getting-started/03-quickstart-server.md@@ -43,15 +43,47 @@ import openviking as ovclient = ov.SyncHTTPClient(url="http://localhost:1933")```-If the server has authentication enabled, pass the API key and optionally an agent ID:+### Authentication++When authentication is enabled, pass an API key. OpenViking uses a two-tier key system:++**Regular data access: use a `user_key` (recommended)**++For most scenarios, use a `user_key` — it directly works with tenant-scoped APIs like `add_resource`, `find`, and `ls`:```pythonimport openviking as ov-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key", agent_id="my-agent")+client = ov.SyncHTTPClient(+ url="http://localhost:1933",+ api_key="<user-key>",+ agent_id="my-agent", # optional+)```-**Full example:**+> `user_key` is created via the Admin API (see [Authentication](../guides/04-authentication.md)). The server can automatically resolve the tenant from the key.++**Administrative operations: use a `root_key`**++`root_key` is for management operations (creating accounts, system status, etc.). To access tenant-scoped APIs with `root_key`, you **must** also pass `account` and `user`:++```python+import openviking as ov++client = ov.SyncHTTPClient(+ url="http://localhost:1933",+ api_key="<root-key>",+ account="acme", # required: target tenant+ user="alice", # required: target user+)+```++> ⚠️ Using `root_key` for `add_resource`, `find`, etc. without `account`/`user` will return:+> `ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers`++See [Authentication](../guides/04-authentication.md) for details (trusted mode, CLI config, etc.).++**Full example (using `user_key`):**```pythonimport openviking as ovdiff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.mdindex 9fcdf9f13..683790609 100644--- a/docs/zh/getting-started/03-quickstart-server.md+++ b/docs/zh/getting-started/03-quickstart-server.md@@ -43,15 +43,47 @@ import openviking as ovclient = ov.SyncHTTPClient(url="http://localhost:1933")```-如果服务端启用了认证,需要传入 `api_key`,可选传入 `agent_id`:+### 启用认证++服务端启用认证后,需要传入 `api_key`。OpenViking 使用两层 API Key 体系,请根据场景选择:++**常规数据访问:使用 `user_key`(推荐)**++大多数场景应使用 `user_key`,可直接调用 `add_resource`、`find`、`ls` 等租户级 API:```pythonimport openviking as ov-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key", agent_id="my-agent")+client = ov.SyncHTTPClient(+ url="http://localhost:1933",+ api_key="<user-key>",+ agent_id="my-agent", # 可选+)```-**完整示例:**+> `user_key` 通过 Admin API 创建(参见 [认证文档](../../guides/04-authentication.md)),服务端可自动识别其所属租户。++**管理操作:使用 `root_key`**++`root_key` 适用于管理操作(创建账户、系统状态等)。如需用 `root_key` 访问租户级 API,**必须**同时传入 `account` 和 `user`,否则服务端会拒绝请求:++```python+import openviking as ov++client = ov.SyncHTTPClient(+ url="http://localhost:1933",+ api_key="<root-key>",+ account="acme", # 必须:目标租户+ user="alice", # 必须:目标用户+)+```++> ⚠️ 使用 `root_key` 调用 `add_resource`、`find` 等租户级 API 时,如果未提供 `account`/`user`,会收到:+> `ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers`++更多认证细节(trusted 模式、CLI 配置等)请参见 [认证文档](../../guides/04-authentication.md)。++**完整示例(使用 `user_key`):**```pythonimport openviking as ovdiff --git a/examples/basic-usage/README.md b/examples/basic-usage/README.mdindex 018165893..0b7e08a9a 100644--- a/examples/basic-usage/README.md+++ b/examples/basic-usage/README.md@@ -91,6 +91,12 @@ import openviking as ovclient = ov.SyncHTTPClient(url="http://localhost:1933")```+> **Multi-tenant auth**: If the server has authentication enabled, use a `user_key` (recommended):+> ```python+> client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="<user-key>")+> ```+> A `root_key` cannot directly call tenant-scoped APIs like `add_resource` or `find` — it requires `account` and `user` parameters. See [Authentication](../../docs/en/guides/04-authentication.md) and [Server Quickstart](../../docs/en/getting-started/03-quickstart-server.md).+### Adding ResourcesAdd URLs, local files, or directories:diff --git a/examples/basic-usage/README_CN.md b/examples/basic-usage/README_CN.mdindex 717ffa5e8..d787d3d35 100644--- a/examples/basic-usage/README_CN.md+++ b/examples/basic-usage/README_CN.md@@ -91,6 +91,12 @@ import openviking as ovclient = ov.SyncHTTPClient(url="http://localhost:1933")```+> **多租户认证**:如果服务端启用了认证,请使用 `user_key`(推荐):+> ```python+> client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="<user-key>")+> ```+> `root_key` 不能直接用于 `add_resource`、`find` 等租户级 API,必须同时传入 `account` 和 `user`。详见 [认证文档](../../docs/zh/guides/04-authentication.md) 和 [快速开始:服务端模式](../../docs/zh/getting-started/03-quickstart-server.md)。+### 添加资源添加 URL、本地文件或目录: