Skip to content

docs: clarify user_key vs root_key in quickstart and basic usage#1077

Open
r266-tech wants to merge 1 commit intovolcengine:mainfrom
r266-tech:docs/user-key-vs-root-key
Open

docs: clarify user_key vs root_key in quickstart and basic usage#1077
r266-tech wants to merge 1 commit intovolcengine:mainfrom
r266-tech:docs/user-key-vs-root-key

Conversation

@r266-tech
Copy link
Copy Markdown
Contributor

Closes #1022

Problem

The quickstart-server.md auth section previously just said "pass api_key" without distinguishing user_key from root_key. This causes users to mistakenly use root_key for tenant-scoped APIs (add_resource, find, ls), which fails with:

ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers.

While the Authentication guide correctly documents this distinction, users naturally start from the quickstart and form an incorrect mental model before ever reaching the auth docs.

Changes

docs/zh/getting-started/03-quickstart-server.md & docs/en/getting-started/03-quickstart-server.md

Expanded the auth section with:

  • Clear explanation of the two-tier key system (user_key vs root_key)
  • user_key example (recommended for most scenarios) — can directly call tenant-scoped APIs
  • root_key example (for management) — must pass account and user for tenant-scoped access
  • ⚠️ Warning showing the exact error message users will see if they use root_key incorrectly
  • Link to the full Authentication guide

examples/basic-usage/README_CN.md & examples/basic-usage/README.md

Added a multi-tenant auth note after the HTTP client mode example, pointing users to the quickstart and auth docs.

The quickstart-server.md auth section previously just said "pass api_key"
without distinguishing user_key from root_key. This causes users to
mistakenly use root_key for tenant-scoped APIs (add_resource, find, ls),
which fails with "ROOT requests to tenant-scoped APIs must include
X-OpenViking-Account and X-OpenViking-User headers".

Changes:
- docs/zh/getting-started/03-quickstart-server.md: expanded auth section
  with user_key (recommended) and root_key (must pass account/user)
  examples, plus warning about the common pitfall
- docs/en/getting-started/03-quickstart-server.md: same changes in English
- examples/basic-usage/README.md: added multi-tenant auth note after
  HTTP client example
- examples/basic-usage/README_CN.md: same note in Chinese

Closes volcengine#1022
@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@github-actions
Copy link
Copy Markdown

Failed to generate code suggestions for PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

[Docs]: server 模式 quickstart/basic usage 应明确区分 user_key 与 root_key + account/user

3 participants