Skip to content

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

docs: align authentication, tenancy and privacy guidance with the server (#5505)

Zayn Jarvisfa4fc64e7092
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index c39346362..e73673263 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -38,8 +38,7 @@ Configure `root_api_key` in `~/.openviking/ovcli.conf`:
{
"url": "http://localhost:1933",
"api_key": "alice-user-key",
- "root_api_key": "your-root-api-key",
- ...
+ "root_api_key": "your-root-api-key"
}
```
@@ -48,7 +47,7 @@ Configure `root_api_key` in `~/.openviking/ovcli.conf`:
- `ov --sudo admin` - Account and user management
- `ov --sudo system` - System utility commands
- `ov --sudo reindex` - Rebuild indexes
-- `ov --sudo admin migrate` - Legacy agent/session migration and cleanup
+- `ov --sudo admin migrate` - Legacy session migration and cleanup
- `ov --sudo task status/list` - Query root/system background tasks, such as migration tasks
### Usage Limitations
@@ -171,6 +170,14 @@ whether the User is named `default`.
| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Complete and publish one template |
| DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Remove that override and restore deployment defaults |
+To update a template while keeping existing customizations:
+
+1. GET the template and copy its `effective` object.
+2. Edit the permitted descriptions or `content_template`, then PUT the complete object. Omitted values revert to deployment defaults.
+3. Check the returned `status` and `effective` values. New extractions use the published template; existing memories are not immediately rewritten.
+
+Use DELETE to restore deployment defaults for that type.
+
The kernel accepts the existing memory YAML structure as a JSON object and enforces
the following editing allowlist at the API boundary. Only these six types are
exposed. Experience, Cases, Trajectories and other types are not exposed for reading
@@ -235,6 +242,8 @@ objects using YAML field names such as `fields[].type`. List returns
`result.account_id` and `result.templates`; single-template operations return
`result.account_id` plus the template result.
+::: details Publication, storage, and concurrent extraction
+
Storage is per Account and per type:
```text
@@ -290,6 +299,8 @@ All eligible Users/Peers in that Account share the templates; no shared deployme
registry is mutated. Publishing/resetting does not proactively rewrite existing
memories; subsequent commits can update them according to the effective rules.
+:::
+
Editable descriptions and content templates must be nonempty strings;
each serialized file is limited to 1 MiB. Descriptions (both type-level and
`fields[].description`) share one restricted Jinja contract, whether they come
@@ -300,9 +311,7 @@ Only the existing `language` context variable is available; body fields,
the same as the restricted bodies below: conditionals, local variables, bounded
literal loops, safe string methods, approved string filters and tests, but no arbitrary calls.
For example, <code v-pre>Use {{ language.upper() }}.</code> renders as `Use EN.` when the existing
-schema-rendering context supplies `language=en`. No new language propagation is
-introduced; the Python protocol's existing static field-description path remains
-unchanged. Missing language retains the previous undefined/empty-output behavior;
+schema-rendering context supplies `language=en`. Rendering uses the language supplied by the calling path; both Python and JSON protocols render field descriptions with that context. Missing language retains the previous undefined/empty-output behavior;
use `language or 'English'` for a fallback. Context values are not recursively
evaluated as Jinja. Invalid custom expressions are rejected before publication,
and persisted overrides are revalidated before extraction. Deployment descriptions
@@ -316,8 +325,7 @@ including whitespace and template-like text. This is a per-field source-characte
not a UTF-8 byte, rendered-output or combined-description limit. Oversized updates
return 400 without modifying the active configuration. Publication does not invoke
an LLM. Storage failures/corrupt files
-are reported, not silently treated as defaults. This change adds no public
-file-browser directory, SDK/CLI commands, drafts or version-history UI.
+are reported, not silently treated as defaults. These endpoints have no SDK/CLI wrappers. Use the HTTP API to read, publish, or reset templates.
#### Managed content-template contract
@@ -420,6 +428,12 @@ active configuration remains unchanged. Structurally valid older overrides using
unsupported Jinja can still be read, replaced or reset, but extraction refuses to
execute them unchecked. Corrupt YAML remains an explicit error.
+For example, this `events` PUT body shows only the event name and summary, without ChatLog:
+
+```json
+{"content_template": "# {{ event_name.strip() }}\n\n## Summary\n{{ summary.strip() or 'Pending' }}"}
+```
+
### Runtime Configuration
ROOT can manage Cluster configuration and any Account configuration. ADMIN can
@@ -875,7 +889,7 @@ Create a new workspace with its first admin user.
**Notes:**
- In `trusted` mode, `user_key` is omitted from the response
-- Omit `seed` for the default random API key. Treat seed values as secret material; short seeds can make the key guessable.
+- Omit `seed` for the default random API key. Set `OV_KEY_SEED` to a securely generated secret before running a deterministic example; the Go example also requires `import "os"`. Short or predictable seeds make the key guessable.
- `settings` receives structural and effective Embedding/VectorDB pair validation before the Account and its directories are created. A failed validation leaves no Account, user, or configuration file.
- Account `vlm`, `query_planner`, `embedding`, and `vectordb` are ROOT-only. See [Account Configuration Reference](#account-configuration-reference) above for their schema, lifecycle, and validation. The current Python SDK, CLI, and other SDK Account-creation wrappers do not expose a `settings` argument; use the HTTP API for this capability.
- Account-level namespace isolation settings are no longer supported. User memory uses user-scoped namespaces, and one-to-many external participants are represented with `peer_id`.
@@ -897,8 +911,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "X-API-Key: <root-key>" \
-d '{
"account_id": "acme",
- "admin_user_id": "alice",
- "seed": "alice-seed"
+ "admin_user_id": "alice"
}'
```
@@ -935,31 +948,9 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
}'
```
-**Trusted mode (registered gateway user)**
+**Trusted mode**
-```bash
-# First, register the gateway admin user in api_key mode
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "Content-Type: application/json" \
- -H "X-API-Key: <root-key>" \
- -d '{
- "account_id": "platform",
- "admin_user_id": "gateway-admin"
- }'
-
-# Then use it in trusted mode; admin authorization comes from root_api_key
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "Content-Type: application/json" \
- -H "X-API-Key: <root-key>" \
- -H "X-OpenViking-Account: platform" \
- -H "X-OpenViking-User: gateway-admin" \
- -d '{
- "account_id": "acme",
- "admin_user_id": "alice"
- }'
-```
-
-**Trusted mode (root fallback without identity headers)**
+With `server.root_api_key` configured, use the root key for Admin API requests. No gateway-user registration or switch to `api_key` mode is required. Omit identity headers for these requests to avoid a mismatch with the target account or user in the URL.
```bash
curl -X POST http://localhost:1933/api/v1/admin/accounts \
@@ -982,7 +973,6 @@ client.initialize()
result = client.admin_create_account(
account_id="acme",
admin_user_id="alice",
- seed="alice-seed",
)
print(f"Account created: {result['account_id']}")
print(f"Admin user: {result['admin_user_id']}")
@@ -1015,7 +1005,7 @@ if err != nil {
}
fmt.Println(result["account_id"])
-seed := "alice-seed"
+seed := os.Getenv("OV_KEY_SEED")
result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice", &openviking.AdminCreateAccountOptions{
Seed: &seed,
UserConfig: map[string]any{
@@ -1032,7 +1022,7 @@ result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice",
```bash
# Requires ROOT privileges, use --sudo
ov --sudo admin create-account acme --admin alice
-ov --sudo admin create-account acme --admin alice --seed alice-seed
+ov --sudo admin create-account acme --admin alice --seed "$OV_KEY_SEED"
ov --sudo admin create-account acme-private --admin alice \
--user-config-json '{"add_targets":{"resource_uri":"viking://~/resources","skill_uri":"viking://~/skills"}}'
@@ -1298,7 +1288,7 @@ Register a new user in a workspace.
**Notes:**
- In `trusted` mode, `user_key` is omitted from the response
-- Omit `seed` for the default random API key. Treat seed values as secret material; short seeds can make the key guessable.
+- Omit `seed` for the default random API key. Set `OV_KEY_SEED` to a securely generated secret before running a deterministic example; the Go example also requires `import "os"`. Short or predictable seeds make the key guessable.
- ADMIN can only register users in their own account
- The `"root"` role cannot be minted through user registration
- `user_config.add_targets.resource_uri` must be a writable resource directory URI: `viking://resources` or `viking://resources/...`, `viking://~/resources` or `viking://~/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`.
@@ -1319,8 +1309,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \
-H "X-API-Key: <root-or-admin-key>" \
-d '{
"user_id": "bob",
- "role": "user",
- "seed": "bob-seed"
+ "role": "user"
}'
```
@@ -1336,7 +1325,6 @@ result = client.admin_register_user(
account_id="acme",
user_id="bob",
role="user",
- seed="bob-seed",
)
print(f"User registered: {result['user_id']}")
print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")
@@ -1364,7 +1352,7 @@ if err != nil {
}
fmt.Println(result["user_id"])
-seed := "bob-seed"
+seed := os.Getenv("OV_KEY_SEED")
result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "user", &openviking.AdminRegisterUserOptions{
Seed: &seed,
UserConfig: map[string]any{
@@ -1379,7 +1367,7 @@ result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "u
# Either ROOT or account ADMIN can execute
# If using regular user's api_key who is an ADMIN of acme:
ov admin register-user acme bob --role user
-ov admin register-user acme bob --role user --seed bob-seed
+ov admin register-user acme bob --role user --seed "$OV_KEY_SEED"
# If using root_api_key (--sudo):
ov --sudo admin register-user acme bob --role user
@@ -1429,6 +1417,8 @@ List active users in a workspace. Users with deletion in progress are omitted.
| account_id | str | Yes | - | Workspace ID |
| name | str | No | null | Filter by user ID (wildcard `*` and `?` matching) |
| role | str | No | null | Filter by role |
+| query | str | No | null | HTTP-only, case-insensitive literal substring match on user IDs |
+| include_summary | bool | No | false | HTTP-only, return paginated users and account statistics in an object |
| include_credentials | bool | No | true | HTTP-only. Set false to return `user_id`, `role`, and `api_key_available` without credentials or key prefixes. The default preserves the existing mode-dependent response. |
| limit | int | No | null | Page size (≥1). Omit to return all matches |
| page | int | No | 1 | 1-based page number; only applies when `limit` is set |
@@ -1702,7 +1692,7 @@ fmt.Println(result["role"])
**CLI**
```bash
-# Requires ROOT privileges, use --sudo
+# ROOT example; an acme ADMIN can use `ov admin set-role` without --sudo
ov --sudo admin set-role acme bob admin
```
@@ -1725,12 +1715,12 @@ ov --sudo admin set-role acme bob admin
#### 1. API Implementation Overview
-Regenerate a user's API key. The old key is immediately invalidated.
+Generate and store a user API key. With the default random generation, the old key stops working after a successful update. Reusing the same account, user, and seed reproduces the same key; choose a new seed or omit it when rotating credentials.
**Processing Flow:**
1. Verify requester has ROOT privileges or is an ADMIN of the account
2. Call API Key Manager to regenerate user key
-3. Old key is immediately invalidated
+3. With random generation or a new seed, the old key stops working immediately
4. Return new user key
**Code Entry Points:**
@@ -1750,8 +1740,8 @@ Regenerate a user's API key. The old key is immediately invalidated.
**Notes:**
- ADMIN can only regenerate keys for users in their own account
-- Old key is immediately invalidated, clients using it need to be updated
-- Omit `seed` for the default random regenerated key.
+- With random generation or a new seed, the old key stops working immediately; update clients that use it
+- Omit `seed` for the default random regenerated key. Deterministic examples use `OV_KEY_SEED` or `OV_NEW_KEY_SEED`; set these to a securely generated secret before use. In Go, import `os`. Do not use the example variable names as seed values.
#### 3. Usage Examples
@@ -1765,7 +1755,7 @@ POST /api/v1/admin/accounts/{account_id}/users/{user_id}/key
curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users/bob/key \
-H "Content-Type: application/json" \
-H "X-API-Key: <root-or-admin-key>" \
- -d '{"seed": "bob-new-seed"}'
+ -d '{}'
```
**Python SDK**
@@ -1779,7 +1769,6 @@ client.initialize()
result = client.admin_regenerate_key(
account_id="acme",
user_id="bob",
- seed="bob-new-seed",
)
print(f"New user key: {result['user_key']}")
```
@@ -1799,7 +1788,7 @@ if err != nil {
}
fmt.Println(result["user_key"])
-seed := "bob-new-seed"
+seed := os.Getenv("OV_NEW_KEY_SEED")
result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviking.AdminRegenerateKeyOptions{
Seed: &seed,
})
@@ -1811,7 +1800,7 @@ result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviki
# Either ROOT or account ADMIN can execute
# If using regular user's api_key who is an ADMIN of acme:
ov admin regenerate-key acme bob
-ov admin regenerate-key acme bob --seed bob-new-seed
+ov admin regenerate-key acme bob --seed "$OV_NEW_KEY_SEED"
# If using root_api_key (--sudo):
ov --sudo admin regenerate-key acme bob
```
@@ -1889,7 +1878,7 @@ curl -X POST http://localhost:1933/api/v1/admin/migrate \
-H "X-API-Key: <root-key>" \
-d '{"action": "migrate"}'
-# Clean old namespaces
+# Clean old namespaces after the migration task finishes and migrated data is verified
curl -X POST http://localhost:1933/api/v1/admin/migrate \
-H "Content-Type: application/json" \
-H "X-API-Key: <root-key>" \
@@ -1924,14 +1913,16 @@ fmt.Println(result["task_id"])
```bash
ov --sudo admin migrate --output json
+# Check the returned task with ov --sudo task status <task_id>, then verify migrated data.
ov --sudo admin migrate --cleanup --output json
```
-**Response Example**
+**CLI Response Example (default compact output)**
```json
{
- "task_id": "legacy_migration_..."
+ "ok": true,
+ "result": {"task_id": "6de05fc3-0334-40d6-ba9b-dd317eb4d351"}
}
```
@@ -1943,6 +1934,8 @@ ov --sudo admin migrate --cleanup --output json
### Typical Admin Workflow
+This example includes user and account deletion. Run it only against a disposable workspace; omit the deletion steps when onboarding real users.
+
```bash
# Step 1: ROOT creates workspace with alice as first admin (requires --sudo)
ov --sudo admin create-account acme --admin alice
diff --git a/docs/en/api/10-privacy.md b/docs/en/api/10-privacy.md
index a2b4d4180..5338c4433 100644
--- a/docs/en/api/10-privacy.md
+++ b/docs/en/api/10-privacy.md
@@ -2,7 +2,11 @@
Privacy configs manage sensitive values by `category + target_key` (for example, a skill's `api_key` and `base_url`).
-Each update creates a version snapshot. You can query history and switch the active version.
+Changed values create a version snapshot. You can query history and switch the active version. Submitting the same values as the current version does not create a new version.
+
+These examples use the current user’s API key. In trusted mode, supply the identity headers required by your deployment. Reads and CLI output contain the stored values; `***` below is an example placeholder, not automatic redaction.
+
+Activating a version changes only the values stored in OpenViking. It does not rotate, revoke, or restore credentials at the external provider.
## Endpoint Summary
@@ -16,8 +20,6 @@ Each update creates a version snapshot. You can query history and switch the act
| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | Get a specific version snapshot |
| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | Activate a specific version |
-Detailed sections are below.
-
---
## Common Use Cases
@@ -82,9 +84,7 @@ GET /api/v1/privacy-configs
```bash
curl -X GET http://localhost:1933/api/v1/privacy-configs \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**Response**
@@ -110,9 +110,7 @@ GET /api/v1/privacy-configs/{category}
```bash
curl -X GET http://localhost:1933/api/v1/privacy-configs/skill \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**Response**
@@ -138,9 +136,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}
```bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**Response**
@@ -178,7 +174,7 @@ Write a new version and set it as active.
**Behavior**
-- `values` is written as a full snapshot for that version
+- `values` replaces the complete value map for that version; omitted keys are absent from the new snapshot
- New keys are allowed and persisted
- If `values` is identical to the current version, no new version is created
@@ -200,8 +196,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}
curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice" \
-d '{
"values": {
"api_key": "secret-2",
@@ -248,9 +242,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions
```bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**Response**
@@ -278,9 +270,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions/{version}
```bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions/2" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**Response**
@@ -324,8 +314,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}/activate
curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/activate" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice" \
-d '{"version": 2}'
```
@@ -365,6 +353,9 @@ ov privacy skill byted-viking-search-knowledgebase
ov privacy upsert skill byted-viking-search-knowledgebase \
--values-json '{"api_key":"secret-2","base_url":"https://example.com"}'
+# Read values from a local JSON file instead of command arguments
+ov privacy upsert skill byted-viking-search-knowledgebase --values-file ./privacy-values.json
+
# Partial key update (CLI merges with current first)
ov privacy upsert skill byted-viking-search-knowledgebase \
--key-api_key secret-3
diff --git a/docs/en/concepts/11-multi-tenant.md b/docs/en/concepts/11-multi-tenant.md
index 19026a98a..4bc2acc05 100644
--- a/docs/en/concepts/11-multi-tenant.md
+++ b/docs/en/concepts/11-multi-tenant.md
@@ -1,6 +1,6 @@
# Multi-Tenant
-OpenViking multi-tenancy does not mean "deploy one isolated server per team." Instead, a single OpenViking Server uses `account` and `user` identity boundaries to control sharing and isolation.
+OpenViking multi-tenancy does not mean "deploy one isolated server per team." A single OpenViking Server uses `account` and `user` identity boundaries to control data sharing and isolation.
This model fits two common scenarios:
@@ -40,7 +40,7 @@ With multi-tenancy enabled, you can:
| Role | Scope | Typical capabilities |
|------|-------|----------------------|
-| ROOT | Global | Create/delete accounts, cross-tenant access, user management |
+| ROOT | Global | Create/delete accounts and manage users; not used for tenant data access in API key mode |
| ADMIN | Single account | Manage users in the same account, regenerate user keys |
| USER | Single account | Access its own user/peer/session data and shared resources in the same account |
@@ -57,7 +57,7 @@ In trusted mode, an upstream gateway may also assert `X-OpenViking-Role: user` o
### What `root_api_key` Does
-Once `server.root_api_key` is configured, OpenViking enters formal multi-tenant mode:
+In `api_key` mode, configuring `server.root_api_key` enables key-based account and user management:
- The root key manages accounts and users
- User keys are generated by the Admin API for normal data access
@@ -79,7 +79,8 @@ If `auth_mode = "api_key"` and `root_api_key` is not configured, the server runs
| User resources (`viking://user/{user_id}/resources`) | No | No | user |
| Peer resources (`viking://user/{user_id}/peers/{peer_id}/resources`) | No | No | user / peer |
| Memories | No | No | user / peer |
-| Skills | No | No | user |
+| Private skills (`viking://user/{user_id}/skills`) | No | No | user |
+| Shared skills (`viking://agent/skills`) | No | Yes, subject to access permissions | account |
| Sessions | No | No | user / session |
### Storage Layer
@@ -109,9 +110,9 @@ So multi-tenant isolation does not rely on a special public URI format. It relie
Filesystem operations and semantic retrieval are tenant-aware:
- Non-ROOT requests are automatically filtered by `account_id`
-- `resources` includes account-shared resources by default and uses effective ACLs when configured
+- `resources` includes account-shared resources by default and uses effective ACLs when account-level `acl.enabled` is on and grants are configured
- User resources remain isolated to the current user space; move them to `viking://resources` to share them
-- `memory` and `skill` remain filtered by the current user space
+- Memories and private skills remain filtered by the current user space; shared skills live at `viking://agent/skills` inside the account
- An actor peer filters `viking://user/{user}/peers` to one peer for filesystem and retrieval operations
This keeps "what you can search" aligned with "what you can read."
@@ -239,43 +240,36 @@ If you give the plugin a root key directly, normal tenant-scoped data APIs will
not have a key-bound tenant user, so that is not a good default for day-to-day
access.
-### Vikingbot: root key manages many end users
+### VikingBot: Match the Server Authentication Mode
-Vikingbot uses a different practice. It behaves more like a platform serving many end users:
+Current VikingBot selects its connection through `bot.ov_server.api_key_type`. It does not automatically register each end user and cache a user key using a root key:
-- The bot connects to OpenViking with a root key
-- The bot config fixes an `account_id`
-- The bot automatically registers users inside that account
-- The bot caches per-user user keys and uses them for memory commit/search whenever possible
+- `user`: connect to an `api_key` Server using a User/Admin `api_key`; the key determines data identity.
+- `root`: use a trusted Server connection to assert account/user identity. This key cannot access tenant data on an `api_key` Server.
+- A Bot started from the same configuration can inherit the current Server connection; configure external Server connections explicitly.
-Example config:
+Example for a fixed user identity:
```json
{
"bot": {
"ov_server": {
"server_url": "http://127.0.0.1:1933",
- "root_api_key": "test",
- "account_id": "default",
- "admin_user_id": "default"
+ "api_key_type": "user",
+ "api_key": "your-user-api-key"
}
}
}
```
-Characteristics of this model:
-
-- Good for one bot service serving many chat users
-- `resources` are shared by default inside the same account; ACLs can refine access to individual directories or files
-- User memories are isolated through auto-managed user identities
-- The bot takes on more tenant lifecycle management logic than the OpenClaw plugin
+Chat participants sharing one user key remain inside one OpenViking user boundary. `actor_peer_id` can restrict the peer collection view, but does not make that user's own memories or shared resources private to each participant. For separate user boundaries, a trusted entry point must supply distinct user connections or trusted identities; see [VikingBot Installation and Configuration](../guides/17-vikingbot.md).
## Which Practice to Choose
| Scenario | Recommended pattern |
|----------|---------------------|
| One OpenClaw instance maps to one fixed identity | OpenClaw plugin + user key |
-| One gateway or bot service serves many end users | Vikingbot + root-key-managed users |
+| One gateway or bot service serves many end users | Per-user connections or trusted identity forwarding |
| A trusted gateway injects identity upstream | `trusted` mode |
| Local single-user experience without formal tenant isolation | Dev mode without `root_api_key` |
@@ -314,7 +308,7 @@ That is only dev mode:
### 4. OpenClaw plugin and Vikingbot are not the same multi-tenant pattern
- OpenClaw plugin is closer to "a client directly uses one user identity"
-- Vikingbot is closer to "a platform manages many users and their user keys"
+- VikingBot supports a fixed User/Admin key or trusted identity forwarding, according to the Server authentication mode
## Related Documentation
diff --git a/docs/en/concepts/13-privacy.md b/docs/en/concepts/13-privacy.md
index 8e4774d4f..c42317816 100644
--- a/docs/en/concepts/13-privacy.md
+++ b/docs/en/concepts/13-privacy.md
@@ -4,7 +4,7 @@ This page explains OpenViking privacy configs and how they work with skill write
## Goal
-Privacy configs separate sensitive values (such as `api_key`, `token`, `base_url`) from skill body content so plaintext is not permanently stored in `SKILL.md`, while keeping full version management and rollback.
+Privacy configs separate sensitive values (such as `api_key`, `token`, `base_url`) from skill body content to reduce plaintext storage of recognized values in `SKILL.md`, with version lookup and switching. Extraction relies on a model and replaces only recognized, matched spans; it does not guarantee discovery of every sensitive value.
Core goals:
@@ -24,7 +24,7 @@ Privacy configs are keyed by `category + target_key`.
Storage layout in user space:
```
-viking://user/{user_space}/privacy/{category}/{target_key}/
+viking://user/{user_id}/privacy/{category}/{target_key}/
├── .meta.json # metadata (active_version/latest_version/labels, etc.)
├── current.json # active version snapshot
└── history/
@@ -45,11 +45,13 @@ viking://user/{user_space}/privacy/{category}/{target_key}/
- If `values` is identical to current `values`, no new version is created
- Otherwise a new version is created and activated
- New keys are allowed (no unknown-key rejection)
+- `values` is a full snapshot, not a patch; omitted old keys are absent from the new version
### activate
- Sets a historical version as active (writes back to `current.json`)
- Updates `active_version` in `.meta.json`
+- Does not rotate or revoke credentials at an external service; it only selects the values OpenViking uses
---
@@ -74,7 +76,7 @@ add_skill
3. **Block mapping captured**:
- `original_content_blocks`
- `replacement_content_blocks`
-4. **Persisted content**: stored `SKILL.md` contains placeholders, not plaintext values.
+4. **Persisted content**: matched spans become placeholders; unmatched content remains unchanged. This processes the skill body, not every attached file.
---
@@ -118,6 +120,8 @@ Current matching is suffix-based: `/skills/{name}/SKILL.md`, so it supports user
---
+`read` returns restored values, and extra-config notices also include values. Privacy APIs and historical snapshots can return full values as well. This feature does not redact responses or encrypt storage; see [Storage Encryption](./10-encryption.md) for encryption.
+
## Relationship with CLI/API
- Management plane: Privacy API/CLI for versions (query, write, rollback)
@@ -129,10 +133,10 @@ Common commands:
```bash
ov privacy categories
ov privacy list skill
-ov privacy skill <target_key>
-ov privacy upsert skill <target_key> --values-json '{"api_key":"..."}'
-ov privacy activate skill <target_key> <version>
-ov read viking://user/default/skills/<target_key>/SKILL.md
+ov privacy skill search-web
+ov privacy upsert skill search-web --values-json '{"api_key":"..."}'
+ov privacy activate skill search-web 1
+ov read viking://~/skills/search-web/SKILL.md
```
---
@@ -140,7 +144,7 @@ ov read viking://user/default/skills/<target_key>/SKILL.md
## Benefits
- Reduces plaintext sensitive data exposure in skill content
-- Versioning supports key rotation and fast rollback
+- Version history supports configuration changes after external credential rotation
- Transparent to callers: `read` returns restored executable skill text
- Notice block improves troubleshooting when config is incomplete or over-provisioned
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 2fdf7badf..25ed656ac 100644
--- a/docs/en/guides/04-authentication.md
+++ b/docs/en/guides/04-authentication.md
@@ -2,17 +2,17 @@
OpenViking Server supports multiple built-in authentication modes with role-based access control. The mode is auto-detected if not explicitly configured. In addition, custom authentication plugins can be registered to support arbitrary identity sources.
-> **Recommended:** API Key mode is the most common and secure default choice, suitable for most deployment scenarios.
+API Key mode is recommended for most deployments; it is auto-selected when no mode is specified and a nonempty root key is configured. Use API Key mode when OpenViking should manage credentials, OIDC or LDAP for an existing identity service, and Trusted mode behind a gateway that validates callers.
## Authentication Modes Overview
-| Mode | `server.auth_mode` | Identity Source | Typical Use | Recommendation |
-|------|--------------------|-----------------|-------------|----------------|
-| **API Key Mode** ⭐ | `api_key` | API key. Data ownership is resolved from the user/admin key. | Standard multi-tenant deployment | ⭐⭐⭐⭐⭐ |
-| **OIDC Mode** | `oidc` | JWT tokens from external identity providers | Enterprise SSO integration with Okta/Auth0/Keycloak | ⭐⭐⭐⭐ |
-| **LDAP Mode** | `ldap` | Enterprise LDAP/AD directory services | Integrate with existing enterprise user directory | ⭐⭐⭐⭐ |
-| **Trusted Mode** | `trusted` | `X-OpenViking-Account` / `X-OpenViking-User`, plus `root_api_key` on non-localhost deployments. Role is looked up from APIKeyManager if the user exists. | Behind a trusted gateway or internal network boundary | ⭐⭐⭐ |
-| **Dev Mode** | `dev` | No authentication, always ROOT | Local development only | ⭐⭐ |
+| Mode | `server.auth_mode` | Identity Source | Typical Use |
+|------|--------------------|-----------------|-------------|
+| **API Key Mode** | `api_key` | API key. Data ownership is resolved from the user/admin key. | Standard multi-tenant deployment |
+| **OIDC Mode** | `oidc` | JWT tokens from external identity providers | Enterprise SSO integration with Okta/Auth0/Keycloak |
+| **LDAP Mode** | `ldap` | Enterprise LDAP/AD directory services | Integrate with existing enterprise user directory |
+| **Trusted Mode** | `trusted` | `X-OpenViking-Account` / `X-OpenViking-User`, plus `root_api_key` on non-localhost deployments. Role is looked up from APIKeyManager if the user exists. | Behind a trusted gateway or internal network boundary |
+| **Dev Mode** | `dev` | No authentication, always ROOT | Local development only |
If `auth_mode` is not explicitly configured:
- If `root_api_key` is set (non-empty): auto-selects `api_key` mode
@@ -22,7 +22,7 @@ If `auth_mode` is not explicitly configured:
## Quick Start: API Key Mode (Recommended)
-API Key mode is the most secure and easiest default choice.
+API Key mode uses a root key for account administration and user/admin keys for tenant data access.
### Configuration
@@ -74,33 +74,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \
ACL groups are the exception: groups and memberships are maintained through the [Admin API](../api/08-admin.md#groups), and members must be registered users in the current account. Clients cannot assert groups through headers or token claims. After authentication, the server resolves the group registry into `RequestContext.group_ids` for that request.
-Trusted deployments can also call Admin API through a trusted gateway. There are two supported patterns:
-
-- Present the trusted deployment's `root_api_key`. For `/api/v1/admin/*`, the server treats the request as ROOT after validating that key.
-- Optionally also present `X-OpenViking-Account` + `X-OpenViking-User` when the admin route targets a specific account/user. Those headers must match the target URL and are kept as the request identity, but authorization still comes from the trusted `root_api_key`.
-
-The role-update API only promotes users to ADMIN. Trusted Admin API authorization comes from the validated deployment root key; creating a ROOT user is not required or supported.
-
-Example using a trusted upstream identity:
-
-```bash
-# First, register the gateway admin (do this once in api_key mode)
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
- -H "Content-Type: application/json" \
- -d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'
-
-# Then, in trusted mode, use that identity to call Admin API
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
- -H "X-OpenViking-Account: platform" \
- -H "X-OpenViking-User: gateway-admin" \
- -H "Content-Type: application/json" \
- -d '{
- "account_id": "acme",
- "admin_user_id": "alice"
- }'
-```
+For gateway deployments, see [Trusted Mode](#trusted-mode) for identity headers and Admin API access.
### Client Usage
@@ -113,7 +87,7 @@ curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
-H "X-API-Key: <user-key>"
```
-**Authorization: Bearer ***
+**Authorization: Bearer header**
```bash
curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
@@ -142,7 +116,7 @@ client = ov.SyncHTTPClient(
When you use a user key or admin key, the server derives `account` and `user` from the key. Do not send `X-OpenViking-Account` / `X-OpenViking-User` in `api_key` mode; those identity headers are accepted only in `trusted` mode.
-**CLI override flags**
+**CLI request**
```bash
ov ls viking://
@@ -527,7 +501,7 @@ Clients submit credentials using Basic Auth:
```bash
curl https://openviking.example.com/api/v1/fs/ls?uri=viking:// \
- -u alice:password123
+ -u alice
```
## Trusted Mode
@@ -562,25 +536,13 @@ Trusted deployments can also call Admin API through a trusted gateway. There are
1. Present the trusted deployment's `root_api_key`. For `/api/v1/admin/*`, the server treats the request as ROOT after validating that key.
2. Optionally also present `X-OpenViking-Account` + `X-OpenViking-User` when the admin route targets a specific account/user. Those headers must match the target URL and are kept as the request identity, but authorization still comes from the trusted `root_api_key`.
-Example using a trusted upstream identity:
+A trusted deployment with a configured root key can create an account directly; switching to API key mode or registering a gateway user first is unnecessary.
```bash
-# First, register the gateway admin (do this once in api_key mode)
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
- -H "Content-Type: application/json" \
- -d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'
-
-# Then use that identity in trusted mode; admin authorization comes from root_api_key
curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "X-API-Key: your-secret-root-key" \
- -H "X-OpenViking-Account: platform" \
- -H "X-OpenViking-User: gateway-admin" \
-H "Content-Type: application/json" \
- -d '{
- "account_id": "acme",
- "admin_user_id": "alice"
- }'
+ -d '{"account_id": "acme", "admin_user_id": "alice"}'
```
### Trusted Mode Client Configuration
@@ -597,6 +559,8 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
}
```
+The curl and SDK examples below use the localhost configuration without a root key. If one is configured, also provide it as `X-API-Key` or SDK `api_key`.
+
**curl Example**
```bash
@@ -619,7 +583,7 @@ client = ov.SyncHTTPClient(
## Dev Mode
-When `auth_mode = "dev"` (or auto-detected when no `root_api_key` is configured), authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) in `dev` mode, the server will refuse to start.
+When `auth_mode = "dev"` (or auto-detected when no `root_api_key` is configured), authentication is disabled. Requests are accepted as ROOT; account/user default to `default` when identity headers are absent. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) in `dev` mode, the server will refuse to start.
```json
{
@@ -642,13 +606,13 @@ Or explicitly:
}
```
-> **Security note:** The default `host` is `127.0.0.1`. If you need to expose the server on the network, you **must** configure `root_api_key`.
+> The default `host` is `127.0.0.1`. Before binding to a network address, choose and configure API Key, OIDC, LDAP, or a protected Trusted deployment. Dev mode refuses non-loopback addresses.
## Roles and Permissions
| Role | Scope | Capabilities |
|------|-------|-------------|
-| ROOT | Global | All operations + Admin API (create/delete accounts, manage users) |
+| ROOT | Deployment administration | Admin API and selected system operations; a root API key cannot access tenant data in API key mode |
| ADMIN | Own account | Regular operations + manage users in own account |
| USER | Own account | Regular operations (ls, read, find, sessions, etc.) |
@@ -723,10 +687,10 @@ The built-in `Role` class supports dynamic registration of custom roles with pri
```python
from openviking.server.identity import Role
-Role.register("operator", rank=1) # Between USER (0) and ADMIN (1)
+Role.register("operator", rank=1) # Same rank as ADMIN for downgrade checks
```
-Custom roles work with `require_role()` and `require_auth_role()` decorators out of the box.
+The rank is used for downgrade checks; it does not inherit ADMIN permissions. `require_role()` and `require_auth_role()` check explicit role names, so a route must list the custom role to accept it.
---
@@ -745,8 +709,7 @@ Edit `~/.openviking/ovcli.conf` to add LDAP authentication settings:
"url": "http://localhost:1933",
"auth_mode": "ldap",
"ldap_username": "alice",
- "ldap_password": "password123",
- "account": "default"
+ "ldap_password": "your-ldap-password"
}
```
@@ -757,12 +720,11 @@ Edit `~/.openviking/ovcli.conf` to add LDAP authentication settings:
| `url` | Yes | OpenViking server URL |
| `auth_mode` | Yes | Authentication mode, set to `"ldap"` to enable LDAP |
| `ldap_username` | Yes | LDAP username (UID) |
-| `ldap_password` | No | LDAP password (omit to skip password in CLI) |
-| `account` | No | OpenViking account ID (defaults to `"default"`) |
+| `ldap_password` | Yes | LDAP password; without it the CLI does not send Basic Auth |
#### 2. Mixed Configuration
-You can configure some settings in the file and override others with environment variables (e.g. `OPENVIKING_URL`, `OPENVIKING_ACCOUNT`).
+Use `OPENVIKING_CLI_CONFIG_FILE` to select another complete configuration file. The `ov` CLI does not use `OPENVIKING_URL` or `OPENVIKING_ACCOUNT` as connection overrides (except `ov chat`, which derives the bot endpoint from `OPENVIKING_URL`); those variables configure Agent plugins.
### Using the CLI
@@ -795,7 +757,7 @@ You can switch between LDAP and API Key authentication by editing `~/.openviking
### Security Recommendations
-1. **Avoid storing plaintext passwords**: Prefer environment variables or secret managers over hardcoding in config files
+1. **Restrict config-file access**: The current CLI reads the LDAP password from its config file. Limit read access to the current user and keep the file out of repositories and shared logs
2. **Use HTTPS**: Always use HTTPS in production environments
3. **Least privilege**: Use regular user accounts for daily operations, admin accounts only for management tasks
4. **Rotate passwords regularly**: Follow your organization's password security policy
@@ -804,7 +766,7 @@ You can switch between LDAP and API Key authentication by editing `~/.openviking
**"Missing LDAP credentials" error:**
- Check that `auth_mode` is set to `"ldap"`
-- Verify `username` and `password` are configured correctly
+- Verify `ldap_username` and `ldap_password` are configured correctly
**"LDAP authentication failed" error:**
- Verify LDAP username and password are correct
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index aff527e67..0ab72eb83 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -38,8 +38,7 @@ Admin API 用于多租户环境下的账户、用户和用户组管理。包括
{
"url": "http://localhost:1933",
"api_key": "alice-user-key",
- "root_api_key": "your-root-api-key",
- ...
+ "root_api_key": "your-root-api-key"
}
```
@@ -48,7 +47,7 @@ Admin API 用于多租户环境下的账户、用户和用户组管理。包括
- `ov --sudo admin` - 账户和用户管理
- `ov --sudo system` - 系统工具命令
- `ov --sudo reindex` - 重建索引
-- `ov --sudo admin migrate` - legacy agent/session 迁移和 cleanup
+- `ov --sudo admin migrate` - 旧 Session 迁移和清理
- `ov --sudo task status/list` - 查询 root/system 后台任务,例如迁移任务
### 使用限制
@@ -166,6 +165,14 @@ ROOT 可管理任意 Account;ADMIN 仅可管理自己 Account 的模板;普
| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 补齐并发布单个模板 |
| DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 删除该模板覆盖,恢复部署默认值 |
+保留已有自定义内容并更新模板时,按以下步骤操作:
+
+1. GET 目标模板,取出 `effective` 对象。
+2. 修改允许编辑的说明或 `content_template`,再 PUT 整个对象。省略的配置会恢复部署默认值。
+3. 核对返回的 `status` 和 `effective`。后续开始的抽取使用新模板,已有记忆不会立即重写。
+
+需要恢复该类型的部署默认值时,调用 DELETE。
+
内核接收原有 Memory YAML 结构对应的 JSON 对象,并在接口层强制校验以下白名单。
仅开放下列六类模板;Experience、Cases、Trajectories 等其他类型不开放查询或编辑,
不支持通过接口新增、删除或重命名 Memory Type。DELETE 仅移除自定义覆盖,不删除模板类型。
@@ -220,6 +227,8 @@ DELETE 始终移除该类型的覆盖;重复 PUT 默认配置或 DELETE 都是
对象使用 YAML 字段名,例如 `fields[].type`。列表接口返回 `result.account_id` 和
`result.templates`;单模板操作返回 `result.account_id` 及上述模板结果。
+::: details 发布、存储与并发抽取的处理方式
+
按 Account、按模板独立存储:
```text
@@ -259,15 +268,17 @@ Registry;无关类型变更不会触发拆批。不同 Schema 分开合并、
不同 Account 不串用,也不修改共享的部署 Registry。发布或恢复默认不会主动重写历史
记忆,后续 Commit 可按生效规则更新已有记忆。
+:::
+
白名单内提交的说明和正文模板必须是非空字符串;单文件序列化后不超过 1 MiB。
`description`(类型说明及 `fields[].description`)统一支持受限 Jinja,不因来自部署默认值或账户覆盖而改变规则,不再记录或检查说明来源标志。
仅开放已有上下文中的 `language`,不开放正文变量、`extract_context` 或任意对象。语法复用下节受限正文的条件、局部变量、有界字面量循环、安全字符串方法、白名单字符串过滤器及测试;不支持任意调用。
例如已有 Schema 渲染上下文提供 `language=en` 时,<code v-pre>请使用 {{ language.upper() }}。</code> 会展开为 `请使用 EN。`,用户修改文字不会让变量停止展开。
-本次不新增语言传递链路,Python 协议原有的静态字段说明展示路径保持不变。缺失语言时保留原来的 undefined/空字符串行为,可用 `language or '中文'` 提供回退;上下文值中的 Jinja 不会被递归执行。
+渲染使用调用路径传入的语言,Python 和 JSON 协议均使用该上下文渲染字段说明。缺失语言时保留原来的 undefined/空字符串行为,可用 `language or '中文'` 提供回退;上下文值中的 Jinja 不会被递归执行。
越界的自定义表达式在保存前拒绝,已保存说明在抽取加载时重新校验;部署说明渲染也受同样限制,已有部署若使用白名单外语法,需要调整,不能凭来源绕过限制。
每条说明最多 2048 个 AST 节点,渲染结果最多 1 MiB。正文 `content_template` 的变量、源码大小及默认正文兼容规则仍按下节处理。
每个可编辑 `description` 最多 50,000 个 Unicode 码点,按提交的原文计数,包含空格、换行和模板样式的文字,不按 UTF-8 字节或渲染后的长度计数。各说明独立计数,不合并计算;整个配置仍受 1 MiB 上限约束。超过上限返回 400,不修改当前配置。
-发布不调用 LLM。存储错误或文件损坏明确报错,不伪装成系统默认。本次不增加公共文件浏览目录、SDK/CLI 命令、草稿或历史版本 UI。
+发布不调用 LLM。存储错误或文件损坏明确报错,不伪装成系统默认。这些接口暂无 SDK/CLI 封装,读取、发布和恢复模板均使用 HTTP API。
#### content_template 的编辑与执行边界
@@ -335,7 +346,7 @@ Events 的默认 embedding 模板引用正文,因此正文变化也可能影
失败不修改当前发布配置。此前保存的、结构有效但使用不支持 Jinja 的模板仍可读取、重新发布或恢复默认;
不会绕过新规则继续执行,抽取加载时提示修复。损坏 YAML 仍明确报错。
-示例:只展示事件名称和摘要,不输出 ChatLog:
+示例:以下 `events` 的 PUT 请求体只展示事件名称和摘要,不输出 ChatLog:
```json
{"content_template": "# {{ event_name.strip() }}\n\n## 事件摘要\n{{ summary.strip() or '待补充' }}"}
@@ -756,7 +767,7 @@ User override 并重新继承上述默认值,请 PATCH `{"memory_policy": null
**说明:**
- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段
-- 省略 `seed` 时使用默认随机 API Key。seed 应视为密钥材料;过短的 seed 会让 key 更容易被猜测。
+- 省略 `seed` 时随机生成 API Key。运行确定性示例前,将 `OV_KEY_SEED` 设为安全生成的秘密值;Go 示例还需导入 `os`。不要使用短字符串或可预测内容作为 seed。
- `settings` 在账号和目录创建前完成结构与有效 Embedding/VectorDB 联合校验。校验失败不会留下 Account、用户或配置文件。
- Account `vlm`、`query_planner`、`embedding` 和 `vectordb` 是 ROOT-only 配置;字段 schema、生命周期和校验见上文 [Account Configuration 接口参考](#account-configuration-接口参考)。当前 Python SDK、CLI 及其他 SDK 的创建账号封装尚未暴露 `settings` 参数,使用此能力请直接调用 HTTP API。
- 不再支持 account 级 namespace 隔离配置。用户记忆使用 user-scoped namespace,一对多外部参与者通过 `peer_id` 表达。
@@ -778,8 +789,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
-H "X-API-Key: <root-key>" \
-d '{
"account_id": "acme",
- "admin_user_id": "alice",
- "seed": "alice-seed"
+ "admin_user_id": "alice"
}'
```
@@ -816,31 +826,9 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
}'
```
-`trusted` 模式示例:
+**trusted 模式**
-```bash
-# 首先,在 api_key 模式下注册网关管理员用户
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "Content-Type: application/json" \
- -H "X-API-Key: <root-key>" \
- -d '{
- "account_id": "platform",
- "admin_user_id": "gateway-admin"
- }'
-
-# 然后在 trusted 模式下使用;管理权限来自 root_api_key
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "Content-Type: application/json" \
- -H "X-API-Key: <root-key>" \
- -H "X-OpenViking-Account: platform" \
- -H "X-OpenViking-User: gateway-admin" \
- -d '{
- "account_id": "acme",
- "admin_user_id": "alice"
- }'
-```
-
-`trusted` 模式也支持"不带身份头"的 ROOT 回退写法:
+配置 `server.root_api_key` 后,直接用 root key 调用 Admin API;无需先注册网关用户,也无需切换到 `api_key` 模式。这类请求可以省略身份头,避免与 URL 中的目标 account/user 不匹配。
```bash
curl -X POST http://localhost:1933/api/v1/admin/accounts \
@@ -863,7 +851,6 @@ client.initialize()
result = client.admin_create_account(
account_id="acme",
admin_user_id="alice",
- seed="alice-seed",
)
print(f"Account created: {result['account_id']}")
print(f"Admin user: {result['admin_user_id']}")
@@ -896,7 +883,7 @@ if err != nil {
}
fmt.Println(result["account_id"])
-seed := "alice-seed"
+seed := os.Getenv("OV_KEY_SEED")
result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice", &openviking.AdminCreateAccountOptions{
Seed: &seed,
UserConfig: map[string]any{
@@ -913,7 +900,7 @@ result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice",
```bash
# 需要 ROOT 权限,使用 --sudo
ov --sudo admin create-account acme --admin alice
-ov --sudo admin create-account acme --admin alice --seed alice-seed
+ov --sudo admin create-account acme --admin alice --seed "$OV_KEY_SEED"
ov --sudo admin create-account acme-private --admin alice \
--user-config-json '{"add_targets":{"resource_uri":"viking://~/resources","skill_uri":"viking://~/skills"}}'
@@ -1177,7 +1164,7 @@ ov --sudo task status <task_id>
**说明:**
- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段
-- 省略 `seed` 时使用默认随机 API Key。seed 应视为密钥材料;过短的 seed 会让 key 更容易被猜测。
+- 省略 `seed` 时随机生成 API Key。运行确定性示例前,将 `OV_KEY_SEED` 设为安全生成的秘密值;Go 示例还需导入 `os`。不要使用短字符串或可预测内容作为 seed。
- ADMIN 只能在自己所属的 account 中注册用户
- 无法通过用户注册接口直接创建 `"root"` 角色
- `user_config.add_targets.resource_uri` 必须是可写资源目录 URI:`viking://resources` 或 `viking://resources/...`、`viking://~/resources` 或 `viking://~/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。
@@ -1198,8 +1185,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \
-H "X-API-Key: <root-or-admin-key>" \
-d '{
"user_id": "bob",
- "role": "user",
- "seed": "bob-seed"
+ "role": "user"
}'
```
@@ -1215,7 +1201,6 @@ result = client.admin_register_user(
account_id="acme",
user_id="bob",
role="user",
- seed="bob-seed",
)
print(f"User registered: {result['user_id']}")
print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")
@@ -1243,7 +1228,7 @@ if err != nil {
}
fmt.Println(result["user_id"])
-seed := "bob-seed"
+seed := os.Getenv("OV_KEY_SEED")
result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "user", &openviking.AdminRegisterUserOptions{
Seed: &seed,
UserConfig: map[string]any{
@@ -1258,7 +1243,7 @@ result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "u
# ROOT 或本账户的 ADMIN 都可以执行
# 如果使用普通用户的 api_key 但该用户是 acme 的 ADMIN:
ov admin register-user acme bob --role user
-ov admin register-user acme bob --role user --seed bob-seed
+ov admin register-user acme bob --role user --seed "$OV_KEY_SEED"
# 如果使用 root_api_key(--sudo):
ov --sudo admin register-user acme bob --role user
@@ -1308,6 +1293,8 @@ ov admin register-user acme bob-private --role user \
| account_id | str | 是 | - | 工作区 ID |
| name | str | 否 | null | 按用户 ID 过滤(通配符 `*` 和 `?` 匹配) |
| role | str | 否 | null | 按角色过滤 |
+| query | str | 否 | null | 仅 HTTP,按用户 ID 做不区分大小写的字面包含匹配 |
+| include_summary | bool | 否 | false | 仅 HTTP,以对象返回分页用户和账号统计 |
| include_credentials | bool | 否 | true | 仅 HTTP。设为 false 时仅返回 `user_id`、`role` 和 `api_key_available`,不返回密钥或前缀;默认保持现有按鉴权模式返回字段的行为。 |
| limit | int | 否 | null | 每页数量(≥1)。省略则返回所有匹配项 |
| page | int | 否 | 1 | 从 1 开始的页码;仅在设置了 `limit` 时生效 |
@@ -1580,7 +1567,7 @@ fmt.Println(result["role"])
**CLI**
```bash
-# 需要 ROOT 权限,使用 --sudo
+# ROOT 调用示例;acme 的 ADMIN 可用 ov admin set-role,无需 --sudo
ov --sudo admin set-role acme bob admin
```
@@ -1603,12 +1590,12 @@ ov --sudo admin set-role acme bob admin
#### 1. API 实现介绍
-重新生成用户的 API Key,旧 Key 立即失效。
+生成并保存用户的 API Key。默认随机生成时,更新成功后旧 Key 失效。同一 account、user 和 seed 会生成相同的 Key;轮换密钥时应使用新 seed,或省略 seed。
**处理流程:**
1. 验证请求者具有 ROOT 权限,或为本账户的 ADMIN
2. 调用 API Key Manager 重新生成用户密钥
-3. 旧密钥立即失效
+3. 随机生成或使用新 seed 时,旧密钥立即失效
4. 返回新的用户密钥
**代码入口:**
@@ -1628,8 +1615,8 @@ ov --sudo admin set-role acme bob admin
**说明:**
- ADMIN 只能为自己所属的 account 中的用户重新生成密钥
-- 旧密钥会立即失效,需要更新使用该密钥的客户端
-- 省略 `seed` 时使用默认随机重新生成逻辑。
+- 随机生成或使用新 seed 时,旧密钥立即失效,需要更新使用该密钥的客户端
+- 省略 `seed` 时随机生成新密钥。确定性示例使用 `OV_KEY_SEED` 或 `OV_NEW_KEY_SEED`,运行前需将其设为安全生成的秘密值;Go 示例需导入 `os`。不要把示例变量名直接当作 seed。
#### 3. 使用示例
@@ -1643,7 +1630,7 @@ POST /api/v1/admin/accounts/{account_id}/users/{user_id}/key
curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users/bob/key \
-H "Content-Type: application/json" \
-H "X-API-Key: <root-or-admin-key>" \
- -d '{"seed": "bob-new-seed"}'
+ -d '{}'
```
**Python SDK**
@@ -1657,7 +1644,6 @@ client.initialize()
result = client.admin_regenerate_key(
account_id="acme",
user_id="bob",
- seed="bob-new-seed",
)
print(f"New user key: {result['user_key']}")
```
@@ -1677,7 +1663,7 @@ if err != nil {
}
fmt.Println(result["user_key"])
-seed := "bob-new-seed"
+seed := os.Getenv("OV_NEW_KEY_SEED")
result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviking.AdminRegenerateKeyOptions{
Seed: &seed,
})
@@ -1689,7 +1675,7 @@ result, err = client.AdminRegenerateKeyWithOptions(ctx, "acme", "bob", &openviki
# ROOT 或本账户的 ADMIN 都可以执行
# 如果使用普通用户的 api_key 但该用户是 acme 的 ADMIN:
ov admin regenerate-key acme bob
-ov admin regenerate-key acme bob --seed bob-new-seed
+ov admin regenerate-key acme bob --seed "$OV_NEW_KEY_SEED"
# 如果使用 root_api_key(--sudo):
ov --sudo admin regenerate-key acme bob
```
@@ -1767,7 +1753,7 @@ curl -X POST http://localhost:1933/api/v1/admin/migrate \
-H "X-API-Key: <root-key>" \
-d '{"action": "migrate"}'
-# 清理旧 namespace
+# 迁移任务完成并核对目标数据后,再清理旧 namespace
curl -X POST http://localhost:1933/api/v1/admin/migrate \
-H "Content-Type: application/json" \
-H "X-API-Key: <root-key>" \
@@ -1802,14 +1788,16 @@ fmt.Println(result["task_id"])
```bash
ov --sudo admin migrate --output json
+# 先用 ov --sudo task status <task_id> 查询返回的任务,再核对迁移结果。
ov --sudo admin migrate --cleanup --output json
```
-**响应示例**
+**CLI 响应示例(默认 compact 输出)**
```json
{
- "task_id": "legacy_migration_..."
+ "ok": true,
+ "result": {"task_id": "6de05fc3-0334-40d6-ba9b-dd317eb4d351"}
}
```
@@ -1821,6 +1809,8 @@ ov --sudo admin migrate --cleanup --output json
### 典型管理流程
+示例包含删除用户和工作区的步骤,只应在测试工作区完整执行;为真实用户开通账号时跳过删除步骤。
+
```bash
# 步骤 1:ROOT 创建工作区,指定 alice 为首个 admin(需要 --sudo)
ov --sudo admin create-account acme --admin alice
diff --git a/docs/zh/api/10-privacy.md b/docs/zh/api/10-privacy.md
index 883ee6aa5..8aa83c7a7 100644
--- a/docs/zh/api/10-privacy.md
+++ b/docs/zh/api/10-privacy.md
@@ -2,7 +2,11 @@
隐私配置用于按 `category + target_key` 管理敏感字段版本(如 skill 的 `api_key`、`base_url`)。
-每次更新都会生成版本快照,可查询历史版本并切换生效版本。
+配置值变化时会生成版本快照,可查询历史版本并切换生效版本。提交与当前版本相同的值不会创建新版本。
+
+以下示例使用当前用户的 API Key。trusted 模式需补充部署要求的身份头。读取接口和 CLI 会返回保存的实际值;下文的 `***` 仅为示例占位符,不表示接口自动脱敏。
+
+激活版本只改变 OpenViking 保存的配置,不会替外部服务轮换、撤销或恢复密钥。
## 典型场景
@@ -25,8 +29,6 @@
| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | 获取指定版本详情 |
| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | 激活指定版本 |
-下面按接口逐一展开说明。
-
---
## 数据结构
@@ -82,9 +84,7 @@ GET /api/v1/privacy-configs
```bash
curl -X GET http://localhost:1933/api/v1/privacy-configs \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**响应**
@@ -110,9 +110,7 @@ GET /api/v1/privacy-configs/{category}
```bash
curl -X GET http://localhost:1933/api/v1/privacy-configs/skill \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**响应**
@@ -138,9 +136,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}
```bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**响应**
@@ -178,7 +174,7 @@ curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-sea
**行为说明**
-- `values` 按整包快照写入(本次传入内容成为新版本的 `values`)
+- `values` 完整替换该版本的键值;本次省略的 key 不会出现在新快照中
- 传入新 key 会直接写入(允许新增)
- 若与当前版本完全一致,则复用当前版本号,不新建版本
@@ -200,8 +196,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}
curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice" \
-d '{
"values": {
"api_key": "secret-2",
@@ -248,9 +242,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions
```bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**响应**
@@ -278,9 +270,7 @@ GET /api/v1/privacy-configs/{category}/{target_key}/versions/{version}
```bash
curl -X GET "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/versions/2" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice"
+ -H "X-API-Key: your-key"
```
**响应**
@@ -324,8 +314,6 @@ POST /api/v1/privacy-configs/{category}/{target_key}/activate
curl -X POST "http://localhost:1933/api/v1/privacy-configs/skill/byted-viking-search-knowledgebase/activate" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -H "X-OpenViking-User: alice" \
-d '{"version": 2}'
```
@@ -365,6 +353,9 @@ ov privacy skill byted-viking-search-knowledgebase
ov privacy upsert skill byted-viking-search-knowledgebase \
--values-json '{"api_key":"secret-2","base_url":"https://example.com"}'
+# 从本地 JSON 文件读取值,避免把值直接写入命令参数
+ov privacy upsert skill byted-viking-search-knowledgebase --values-file ./privacy-values.json
+
# 仅更新部分 key(先读取 current 再合并)
ov privacy upsert skill byted-viking-search-knowledgebase \
--key-api_key secret-3
diff --git a/docs/zh/concepts/11-multi-tenant.md b/docs/zh/concepts/11-multi-tenant.md
index 78c77d4b6..c4280b059 100644
--- a/docs/zh/concepts/11-multi-tenant.md
+++ b/docs/zh/concepts/11-multi-tenant.md
@@ -1,6 +1,6 @@
# 多租户
-OpenViking 的多租户不是“为每个团队部署一套独立服务”,而是在同一个 OpenViking Server 内,用 `account` 和 `user` 两层身份边界来隔离和共享数据。
+OpenViking 的多租户不是“为每个团队部署一套独立服务”,而是在同一个 Server 内,通过 `account` 和 `user` 两层身份边界隔离和共享数据。
它适合两类典型场景:
@@ -40,7 +40,7 @@ OpenViking 的多租户不是“为每个团队部署一套独立服务”,而
| 角色 | 作用域 | 典型能力 |
|------|--------|----------|
-| ROOT | 全局 | 创建/删除 account、跨租户访问、管理用户 |
+| ROOT | 全局 | 创建/删除 account、管理用户;API Key 模式下不用于租户数据读写 |
| ADMIN | 单个 account | 管理本 account 的用户、重置 user key |
| USER | 单个 account | 访问自己的 user/peer/session 数据和 account 内共享资源 |
@@ -57,7 +57,7 @@ OpenViking Server 支持两种多租户相关认证模式:
### `root_api_key` 的作用
-配置 `server.root_api_key` 后,OpenViking 才进入正式多租户模式:
+在 `api_key` 模式下,配置 `server.root_api_key` 后启用基于 key 的账户和用户管理:
- Root key 用于管理 account 和 user
- User key 由 Admin API 生成,用于普通业务读写
@@ -79,7 +79,8 @@ OpenViking Server 支持两种多租户相关认证模式:
| 用户资源 (`viking://user/{user_id}/resources`) | 否 | 否 | user |
| Peer 资源 (`viking://user/{user_id}/peers/{peer_id}/resources`) | 否 | 否 | user / peer |
| 记忆 | 否 | 否 | user / peer |
-| 技能 | 否 | 否 | user |
+| 私有技能 (`viking://user/{user_id}/skills`) | 否 | 否 | user |
+| 共享技能 (`viking://agent/skills`) | 否 | 是,受访问权限约束 | account |
| 会话 | 否 | 否 | user / session |
### 存储层
@@ -109,9 +110,9 @@ viking://user/alice/peers/web-visitor-alice/resources/
文件系统操作和语义检索都受租户约束:
- 非 ROOT 请求会自动按 `account_id` 过滤
-- `resources` 默认允许检索 account 内共享资源;设置 ACL 后按有效 ACL 过滤
+- `resources` 默认允许检索 account 内共享资源;开启账号级 `acl.enabled` 并设置 ACL 后按有效 ACL 过滤
- 用户资源始终按当前 `user space` 隔离;需要共享时移动到 `viking://resources`
-- `memory` 和 `skill` 继续按当前 `user space` 过滤
+- 记忆和私有技能按当前 `user space` 过滤;共享技能位于 account 内的 `viking://agent/skills`
- Actor peer 会把 `viking://user/{user}/peers` 过滤到一个 peer,并作用于文件系统和检索操作
这意味着“能搜到什么”与“能读到什么”保持一致,不会因为向量召回而越权。
@@ -236,43 +237,36 @@ openclaw config set plugins.entries.openviking.config.peer_prefix "<peer-prefix>
如果给插件直接配置 root key,则普通租户数据 API 没有从 key 绑定出来的租户用户,
这不适合作为日常读写方式。
-### Vikingbot:root key 代管用户身份
+### VikingBot:匹配 Server 的认证模式
-Vikingbot 当前的实践与 OpenClaw 插件不同,它更接近“平台代理多个终端用户”:
+当前 VikingBot 通过 `bot.ov_server.api_key_type` 选择连接方式,不会通过 root key 自动注册并缓存每个终端用户的 user key:
-- bot 连接 OpenViking 时持有 root key
-- bot 配置固定的 `account_id`
-- bot 会在该 account 下自动注册用户
-- bot 会缓存每个 user 的 user key,并尽量用对应 user key 去提交/检索 memory
+- `user`:连接 `api_key` 模式的 Server,`api_key` 必须是 User/Admin key,数据身份由 key 决定。
+- `root`:用于 trusted 模式,Bot 以受信连接传递 account/user 身份;不能拿它访问 `api_key` 模式的租户数据接口。
+- 同配置启动时可以继承当前 Server 的地址和认证设置;外部 Server 应显式配置连接。
-相关配置示例:
+固定用户身份的配置示例:
```json
{
"bot": {
"ov_server": {
"server_url": "http://127.0.0.1:1933",
- "root_api_key": "test",
- "account_id": "default",
- "admin_user_id": "default"
+ "api_key_type": "user",
+ "api_key": "your-user-api-key"
}
}
}
```
-这种模式的特点:
-
-- 适合一个 bot 服务承载多个聊天用户
-- 同一 account 下的 `resources` 默认共享,ACL 可以对具体目录或文件细化权限
-- 用户记忆通过自动注册的 user 身份隔离
-- bot 侧需要承担更多租户生命周期管理逻辑
+共享同一个 user key 的聊天参与者仍属于同一 OpenViking user。`actor_peer_id` 可限制其 peer 集合视图,但不会把该用户自己的记忆和共享资源变成逐聊天用户私有数据。需要独立 user 边界时,应由可信身份入口提供不同的用户连接或使用 trusted 身份传递,见[VikingBot 安装与配置](../guides/17-vikingbot.md)。
## 什么时候选哪种实践
| 场景 | 推荐方式 |
|------|----------|
| 一个 OpenClaw 实例对应一个固定身份 | OpenClaw 插件 + user key |
-| 一个网关/机器人服务承载很多最终用户 | Vikingbot + root key 代管用户 |
+| 一个网关/机器人服务承载很多最终用户 | 按用户配置连接或由受信入口传递 trusted 身份 |
| 受信网关统一注入身份 | `trusted` 模式 |
| 单机本地体验、无需真正租户隔离 | 开发模式(无 `root_api_key`) |
@@ -310,7 +304,7 @@ peer 集合过滤选择当前用户内的 peer 内容子空间,例如
### 4. OpenClaw 插件和 Vikingbot 不是同一种租户实践
- OpenClaw 插件:更像“客户端拿到一个 user 身份后直接访问”
-- Vikingbot:更像“平台代理多个用户,并代为申请和管理 user key”
+- VikingBot:支持固定 User/Admin key,也可作为受信入口传递身份;选择取决于 Server 认证模式
## 相关文档
diff --git a/docs/zh/concepts/13-privacy.md b/docs/zh/concepts/13-privacy.md
index c873f8d23..bdcf9948d 100644
--- a/docs/zh/concepts/13-privacy.md
+++ b/docs/zh/concepts/13-privacy.md
@@ -4,7 +4,7 @@
## 目标
-隐私配置用于把敏感值(如 `api_key`、`token`、`base_url`)从技能正文中分离出来,避免明文长期存储在 `SKILL.md` 中,同时保留版本化管理与回滚能力。
+隐私配置用于把敏感值(如 `api_key`、`token`、`base_url`)从技能正文中分离出来,减少已识别敏感值在 `SKILL.md` 中的明文存储,并支持版本查询和切换。抽取依赖模型,只替换识别并匹配成功的片段,不能保证发现所有敏感信息。
核心目标:
@@ -24,7 +24,7 @@
用户空间下的存储路径:
```
-viking://user/{user_space}/privacy/{category}/{target_key}/
+viking://user/{user_id}/privacy/{category}/{target_key}/
├── .meta.json # 元信息(active_version/latest_version/labels 等)
├── current.json # 当前生效版本快照
└── history/
@@ -45,11 +45,13 @@ viking://user/{user_space}/privacy/{category}/{target_key}/
- 如果与当前版本 `values` 完全一致,则不新建版本,直接返回当前版本
- 否则创建新版本并自动设为当前生效版本
- 允许新增 key(不会因“未知 key”报错)
+- `values` 是完整快照,不是部分更新;省略的旧 key 不会保留在新版本中
### activate(激活)
- 将历史版本设置为当前生效版本(写回 `current.json`)
- 更新 `.meta.json` 中的 `active_version`
+- 不会轮换或撤销第三方服务中的密钥;这里只切换 OpenViking 使用的值
---
@@ -74,7 +76,7 @@ add_skill
3. **保留块映射**:会同时记录:
- `original_content_blocks`
- `replacement_content_blocks`
-4. **写盘结果**:`SKILL.md` 持久化的是占位符内容,不是明文值。
+4. **写盘结果**:匹配成功的片段以占位符保存,未匹配内容保持原样。该流程处理技能正文,不等于扫描并清理所有附件。
---
@@ -114,10 +116,12 @@ fs.read(uri)
- `Missing config: ...`(如有)
- `Configured but not referenced in content: ...`(如有)
-> 注意:当前实现中,仅当该 skill 已有 `current` 配置时才会进入 restore。若没有当前配置,不会追加 notice。
+> 仅当该 skill 已有 `current` 配置时才会进入 restore。若没有当前配置,不会追加 notice。
---
+`read` 返回的是还原后的值;“额外配置”提示也会包含配置值。Privacy API 和历史快照同样可以返回完整值,该功能不等于响应脱敏或存储加密。需要加密存储时,另见[存储加密](./10-encryption.md)。
+
## 与 CLI/API 的关系
- 管理面:通过 Privacy API/CLI 管理版本(查询、写入、回滚)
@@ -129,10 +133,10 @@ fs.read(uri)
```bash
ov privacy categories
ov privacy list skill
-ov privacy skill <target_key>
-ov privacy upsert skill <target_key> --values-json '{"api_key":"..."}'
-ov privacy activate skill <target_key> <version>
-ov read viking://user/default/skills/<target_key>/SKILL.md
+ov privacy skill search-web
+ov privacy upsert skill search-web --values-json '{"api_key":"..."}'
+ov privacy activate skill search-web 1
+ov read viking://~/skills/search-web/SKILL.md
```
---
@@ -140,7 +144,7 @@ ov read viking://user/default/skills/<target_key>/SKILL.md
## 设计收益
- 降低明文敏感信息在技能正文中的暴露风险
-- 通过版本化支持密钥轮换与快速回滚
+- 为外部密钥轮换后的配置切换保留版本记录
- 对上层调用透明:`read` 即可拿到还原后的可执行技能文本
- 对不完整配置提供可观测提示,便于排障
diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.md
index 2a926e585..bb1248f9e 100644
--- a/docs/zh/guides/04-authentication.md
+++ b/docs/zh/guides/04-authentication.md
@@ -1,44 +1,30 @@
# 认证
-> **先看这里:选择适合你的认证模式**
-
-## 📚 前置知识 - 我该用哪个?
-
-| 认证模式 | 是什么? | 适合谁? | **推荐度** |
-|---------|----------|---------|------------|
-| **API Key** (默认) | OpenViking 自己管理用户和密钥 | 小团队、独立部署 | ⭐⭐⭐⭐⭐ |
-| **OIDC** | 对接企业单点登录(Okta/Auth0/Keycloak/Azure AD 等) | 企业 SSO 集成 | ⭐⭐⭐⭐ |
-| **LDAP** | 对接企业用户目录(Windows AD/OpenLDAP) | 已有企业目录服务 | ⭐⭐⭐⭐ |
-| **Trusted** | 上游网关/反向代理断言身份 | 部署在受信任内网/网关后 | ⭐⭐⭐ |
-| **Dev** | 无认证,仅本地开发 | **只用于本地开发!** | ⭐⭐ |
-
-### 🔍 决策树
-
-```
-┌─────────────────────────────────────────────────────┐
-│ 企业里有现成的身份系统? │
-├─────────────────────────────────────────────────────┤
-│ 是 SaaS 身份?(Okta/Auth0/Keycloak) │
-│ → 用 **OIDC** ✅ │
-│ │
-│ 是本地目录?(Windows AD/OpenLDAP) │
-│ → 用 **LDAP** ✅ │
-├─────────────────────────────────────────────────────┤
-│ 没有身份系统? │
-│ → 用 **API Key**(默认)✅ │
-├─────────────────────────────────────────────────────┤
-│ 部署在内部网关后面? │
-│ → 用 **Trusted** ✅ │
-└─────────────────────────────────────────────────────┘
-```
+选择认证模式后,配置服务端身份来源,再用对应凭证连接客户端。大多数部署推荐使用 API Key 模式;配置非空 root key 后,未指定认证模式时会自动选择 API Key。
+
+## 选择认证模式
+
+| 认证模式 | 是什么? | 适合谁? |
+|---------|----------|---------|
+| **API Key** | OpenViking 自己管理用户和密钥 | 小团队、独立部署 |
+| **OIDC** | 对接企业单点登录(Okta/Auth0/Keycloak/Azure AD 等) | 企业 SSO 集成 |
+| **LDAP** | 对接企业用户目录(Windows AD/OpenLDAP) | 已有企业目录服务 |
+| **Trusted** | 上游网关/反向代理断言身份 | 部署在受信任内网/网关后 |
+| **Dev** | 无认证,仅本地开发 | 本地开发,不接入公网 |
+
+### 决策树
+
+已有单点登录服务选 OIDC,已有企业目录选 LDAP;由网关验证并注入身份时选 Trusted。没有这些上游服务时,使用 API Key 管理账号和凭证。
+
+未显式设置 `auth_mode` 时,有非空 `root_api_key` 会选用 `api_key`,未配置则选用 `dev`。空字符串 `root_api_key` 无效。
---
-## 🏁 快速开始 - 3分钟跑起来
+## 快速开始
-### 方案一:API Key(最简单)
+### 方案一:API Key
-只需要配置 `root_api_key`,剩下的默认就好!
+配置 `root_api_key`,启动后用它创建 account 和首个管理员。日常数据操作使用返回的 user/admin key。
```json
{
@@ -58,13 +44,21 @@ openviking-server
```bash
# 创建账号 + 管理员
curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
+ -H "X-API-Key: your-secret-root-key-here" \
-H "Content-Type: application/json" \
-d '{"account_id": "my-team", "admin_user_id": "alice"}'
```
+创建账号后,保存响应中的 `user_key`,将它用于 CLI、SDK 和数据 API。root key 不用于租户数据读写。
+
### 方案二:OIDC(企业 SSO)
+OIDC 和 LDAP 需要可选认证依赖。在运行服务端的 Python 环境中安装:
+
+```bash
+uv pip install "openviking[auth]"
+```
+
**最小配置(不需要 mapping):**
```json
@@ -83,10 +77,10 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
- `user_id` → 使用 OIDC 标准字段 `sub`
- `role` → 默认为 `user`
-启动后健康检查会自动验证是否连接成功!
+启动后用有效的 OIDC token 请求数据接口,验证身份映射和访问权限;匿名 `/health` 成功只证明服务可访问。
**进阶配置(需要隔离团队时):**
-参考下方「🔧 Identity Mapping 详解」章节。
+参考下方 [Identity Mapping](#identity-mapping-是什么) 和高级 Mapping 示例。
### 方案三:LDAP(企业目录)
@@ -116,7 +110,7 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \
---
-## 📚 概念详解
+## 身份与映射
### OIDC 是什么?
@@ -160,7 +154,7 @@ OIDC Claims: {
---
-## ⚙️ 完整配置参考
+## 完整配置参考
### OIDC 完整配置
@@ -303,7 +297,7 @@ OIDC Claims: {
---
-## 🐛 故障排除
+## 故障排除
### OIDC 常见问题
@@ -392,9 +386,9 @@ OIDC Claims: {
---
-## 🔧 自定义认证插件(高级)
+## 自定义认证插件
-如果内置的模式不够用,可以自己开发!
+需要接入其他身份源时,可以实现并注册自定义认证插件。
服务端采用插件化认证架构。每种 `auth_mode` 对应一个 `AuthPlugin` 实现。内置插件(`dev`, `api_key`, `trusted`, `oidc`, `ldap`)会自动注册;第三方插件可通过继承 `AuthPlugin` 并在启动前注册来扩展。
@@ -440,10 +434,10 @@ class CustomAuthPlugin(AuthPlugin):
```python
from openviking.server.identity import Role
-Role.register("operator", rank=1) # 权限介于 USER (0) 与 ADMIN (1) 之间
+Role.register("operator", rank=1) # 降权检查时,与 ADMIN 同级
```
-自定义角色可直接用于 `require_role()` 和 `require_auth_role()` 装饰器。
+rank 用于降权检查,不会继承 ADMIN 的接口权限。`require_role()` 和 `require_auth_role()` 按角色名检查,路由需要明确允许该自定义角色。
---
@@ -460,14 +454,14 @@ trusted 模式的普通数据面请求无需预先注册 user 或创建 user API
```bash
# 创建工作区 + 首个 admin
curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
+ -H "X-API-Key: your-secret-root-key-here" \
-H "Content-Type: application/json" \
-d '{"account_id": "acme", "admin_user_id": "alice"}'
# 返回: {"result": {"account_id": "acme", "admin_user_id": "alice", "user_key": "..."}}
# 注册普通用户(ROOT 或 ADMIN 均可)
curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \
- -H "X-API-Key: your-secret-root-key" \
+ -H "X-API-Key: your-secret-root-key-here" \
-H "Content-Type: application/json" \
-d '{"user_id": "bob", "role": "user"}'
# 返回: {"result": {"account_id": "acme", "user_id": "bob", "user_key": "..."}}
@@ -482,26 +476,7 @@ ACL 用户组是例外:组和成员通过 [Admin API](../api/08-admin.md#用
角色更新 API 只支持将用户提升为 ADMIN。Trusted Admin API 的管理权限来自已校验的部署 root key,无需也不支持创建 ROOT 用户。
-下面是“受信上游身份”这种方式的示例:
-
-```bash
-# 首先,注册网关管理员(在 api_key 模式下执行一次)
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
- -H "Content-Type: application/json" \
- -d '{"account_id": "platform", "admin_user_id": "gateway-admin"}'
-
-# 然后,在 trusted 模式下使用该身份调用 Admin API
-curl -X POST http://localhost:1933/api/v1/admin/accounts \
- -H "X-API-Key: your-secret-root-key" \
- -H "X-OpenViking-Account: platform" \
- -H "X-OpenViking-User: gateway-admin" \
- -H "Content-Type: application/json" \
- -d '{
- "account_id": "acme",
- "admin_user_id": "alice"
- }'
-```
+配置了 root key 的 Trusted 部署可直接调用上面的 Admin API,无需先切换到 API Key 模式或注册网关管理员。
## 客户端使用
@@ -541,12 +516,12 @@ client = ov.SyncHTTPClient(
}
```
-如果使用普通 `user key` 或 `admin key`,`account` 和 `user` 可以省略,因为服务端可以从 key 反查出来;如果使用 `trusted` 模式,则建议明确配置。
+API Key 模式下,服务端从 user/admin key 解析 account 和 user,不接受用身份请求头切换用户。Trusted 模式下的数据请求需要明确提供 account 和 user。
-**CLI 覆盖参数**
+**CLI 请求**
```bash
-openviking --account acme --user alice ls viking://
+ov ls viking://
```
### 使用 --sudo 和 Root API Key
@@ -618,9 +593,13 @@ Trusted 模式不会查询 user key,而是直接信任每个请求显式携带
}
```
+数据请求必须提供 `X-OpenViking-Account` 和 `X-OpenViking-User`。若配置了 `root_api_key`,请求还必须携带匹配的 API Key,以验证上游网关。
+
+角色默认从已注册用户查询,未注册时为 USER。配置并验证 root key 后,上游可用 `X-OpenViking-Role: user` 或 `admin` 断言角色,不接受 `root`。Admin API 的 ROOT 授权来自部署 root key。
+
### Dev 模式
-当 `auth_mode = "dev"`(或未配置 `root_api_key` 时自动推导)时,认证禁用,所有请求以 ROOT 身份访问 default account。
+当 `auth_mode = "dev"`(或未配置 `root_api_key` 时自动推导)时,认证禁用,请求使用 ROOT 身份;未提供身份请求头时,account 和 user 均为 `default`。Dev 模式只允许监听 `127.0.0.1`、`localhost` 或 `::1`,监听其他地址会拒绝启动。
```json
{
@@ -630,7 +609,7 @@ Trusted 模式不会查询 user key,而是直接信任每个请求显式携带
}
```
-> **安全提示:** 默认 `host` 为 `127.0.0.1`。如果需要将服务暴露到网络,**必须**配置 `root_api_key`。
+> 默认 `host` 为 `127.0.0.1`。监听网络地址前,选择并配置 API Key、OIDC、LDAP 或受保护的 Trusted 部署。
---
@@ -649,8 +628,7 @@ OpenViking CLI (`ov`) 支持通过 LDAP 进行认证。配置完成后,所有
"url": "http://localhost:1933",
"auth_mode": "ldap",
"ldap_username": "alice",
- "ldap_password": "password123",
- "account": "default"
+ "ldap_password": "your-ldap-password"
}
```
@@ -661,12 +639,11 @@ OpenViking CLI (`ov`) 支持通过 LDAP 进行认证。配置完成后,所有
| `url` | 是 | OpenViking 服务器地址 |
| `auth_mode` | 是 | 认证模式,设置为 `"ldap"` 启用 LDAP |
| `ldap_username` | 是 | LDAP 用户名(UID) |
-| `ldap_password` | 否 | LDAP 密码(不提供时 CLI 不发送密码) |
-| `account` | 否 | OpenViking 账户 ID(默认为 `"default"`) |
+| `ldap_password` | 是 | LDAP 密码;缺少此字段时 CLI 不发送 Basic Auth |
#### 2. 混合配置
-可以部分配置在文件中,部分通过环境变量(如 `OPENVIKING_URL`、`OPENVIKING_ACCOUNT`)覆盖。
+用 `OPENVIKING_CLI_CONFIG_FILE` 选择另一份完整配置文件。`ov` 不读取 `OPENVIKING_URL` 或 `OPENVIKING_ACCOUNT` 作为连接覆盖值(`ov chat` 例外,它用 `OPENVIKING_URL` 拼出 bot endpoint);这些变量属于 Agent 插件配置。
### 使用 CLI
@@ -699,7 +676,7 @@ make build-cli
### 安全建议
-1. **避免明文存储密码**:推荐使用环境变量或密钥管理工具,而非在配置文件中硬编码密码
+1. **限制配置文件访问**:当前 CLI 从配置文件读取 LDAP 密码。只允许当前用户读取,避免提交到仓库或写入共享日志
2. **使用 HTTPS**:生产环境中确保服务器使用 HTTPS 连接
3. **最小权限**:使用普通用户账户进行日常操作,管理员账户仅用于管理任务
4. **定期轮换密码**:遵循组织的密码安全策略
@@ -708,7 +685,7 @@ make build-cli
**"Missing LDAP credentials" 错误:**
- 检查 `auth_mode` 是否设置为 `"ldap"`
-- 确认 `username` 和 `password` 配置正确
+- 确认 `ldap_username` 和 `ldap_password` 配置正确
**"LDAP authentication failed" 错误:**
- 验证 LDAP 用户名和密码是否正确
@@ -741,7 +718,7 @@ ov config validate
---
-## 📝 附录:Admin API 参考
+## Admin API 参考
| 方法 | 端点 | 角色 | 说明 |
|------|------|------|------|