Skip to content

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

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.md
index 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 ov
client = 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`:
```python
import 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`):**
```python
import openviking as ov
diff --git a/docs/zh/getting-started/03-quickstart-server.md b/docs/zh/getting-started/03-quickstart-server.md
index 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 ov
client = ov.SyncHTTPClient(url="http://localhost:1933")
```
-如果服务端启用了认证,需要传入 `api_key`,可选传入 `agent_id`:
+### 启用认证
+
+服务端启用认证后,需要传入 `api_key`。OpenViking 使用两层 API Key 体系,请根据场景选择:
+
+**常规数据访问:使用 `user_key`(推荐)**
+
+大多数场景应使用 `user_key`,可直接调用 `add_resource`、`find`、`ls` 等租户级 API:
```python
import 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`):**
```python
import openviking as ov
diff --git a/examples/basic-usage/README.md b/examples/basic-usage/README.md
index 018165893..0b7e08a9a 100644
--- a/examples/basic-usage/README.md
+++ b/examples/basic-usage/README.md
@@ -91,6 +91,12 @@ import openviking as ov
client = 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 Resources
Add URLs, local files, or directories:
diff --git a/examples/basic-usage/README_CN.md b/examples/basic-usage/README_CN.md
index 717ffa5e8..d787d3d35 100644
--- a/examples/basic-usage/README_CN.md
+++ b/examples/basic-usage/README_CN.md
@@ -91,6 +91,12 @@ import openviking as ov
client = 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、本地文件或目录: