From 66d18c378df63e3a3cd2b7c5d0f63309d3effaa7 Mon Sep 17 00:00:00 2001
From: Adarsh <adarsh@neuroad.ai>
Date: Fri, 25 Sep 2026 14:07:36 +0530
Subject: [PATCH 1/8] docs(auth): mark group paths as the GraphSpace-format
 exception

GroupAPI is mounted at /auth/groups on every version, and the
/graphspaces/{graphspace}/auth/groups form only exists from
apache/hugegraph#3096 onward, so on the 1.7.0 release the prefixed group
URL 404s while the page presents it as the 1.7.0+ spelling. Adds the
exception to the version notice and to the group section, in both
languages.

Refs: https://github.com/apache/hugegraph/issues/3019
---
 content/cn/docs/clients/restful-api/auth.md | 11 ++++++++++-
 content/en/docs/clients/restful-api/auth.md |  9 +++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 488ba51a46..680eff4d81 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -8,6 +8,11 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
 > **版本变更说明**:
 > - 1.7.0+: Auth API 路径使用 GraphSpace 格式，如 `/graphspaces/DEFAULT/auth/users`，且 group/target 等 id 格式与 name 一致（如 `admin`）
 > - 1.5.x 及更早: Auth API 路径包含 graph 名称，group/target 等 id 格式类似 `-69:grant`。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+>
+> 用户组路径是例外：`GroupAPI` 在所有版本中都挂载于 `/auth/groups`，不带 GraphSpace 前缀；
+> 下文的 `/graphspaces/{graphspace}/auth/groups` 形式需要包含
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建，晚于 1.7.0 发布版。
+> 在 1.7.0 上带前缀的用户组路径会返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -248,7 +253,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 
 ### 10.3 用户组（Group）API
 用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。  
-用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。
+用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。  
+
+> `GroupAPI` 本身挂载在 `/auth/groups`，不带 GraphSpace 前缀，这也是 1.7.0 上唯一的用户组路径；
+> 下文的 `/graphspaces/DEFAULT/auth/groups` 形式需要包含
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建。
 
 #### 10.3.1 创建用户组
 
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index 7c37de996a..c20333c1b5 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -8,6 +8,11 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 > **Version Change Notice**:
 > - 1.7.0+: Auth API paths use GraphSpace format, such as `/graphspaces/DEFAULT/auth/users`, and group/target IDs match their names (e.g., `admin`)
 > - 1.5.x and earlier: Auth API paths include graph name, and group/target IDs use format like `-69:grant`. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+>
+> Group paths are the exception: `GroupAPI` is mounted at `/auth/groups` in every
+> version, and the `/graphspaces/{graphspace}/auth/groups` forms below need a build
+> that includes [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096),
+> which is newer than the 1.7.0 release. On 1.7.0 the prefixed group path returns 404.
 
 ### 10.1 User Authentication and Access Control
 
@@ -246,6 +251,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 Groups grant corresponding resource permissions, and users are assigned to different groups, thereby having different resource permissions.
 The group interface includes APIs for creating groups, deleting groups, modifying groups, and querying group-related information.
 
+> `GroupAPI` itself is served at `/auth/groups` with no GraphSpace prefix, and that is
+> the only group path on 1.7.0. The `/graphspaces/DEFAULT/auth/groups` form used below
+> needs a build containing [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096).
+
 #### 10.3.1 Create Group
 
 ##### Params

From ffddf63d77a11aa3ab8f9a33be20e5ee2cdab020 Mon Sep 17 00:00:00 2001
From: Adarsh <adarsh@neuroad.ai>
Date: Fri, 25 Sep 2026 14:36:30 +0530
Subject: [PATCH 2/8] docs(auth): scope the group-path exception to 1.7.0

The previous note said GroupAPI is mounted at /auth/groups "in every
version". That is wrong and it contradicts the 1.5.x line directly above
it: at tags 1.2.0, 1.3.0 and 1.5.0 the class is @Path("graphs/{graph}/auth/
groups"), i.e. prefixed with the graph name like the other auth APIs, and
the unprefixed /auth/groups only appears at 1.7.0. GraphSpaceGroupAPI.java
is absent at all of those refs, so no 1.5.x build serves the unprefixed
form either. A reader on 1.5.x sent to /auth/groups by this page would hit
a 404 - the same defect this PR exists to fix.

Verified from source at each ref via the contents API, not inference:
GroupAPI.java @Path at 1.2.0/1.3.0/1.5.0 = graphs/{graph}/auth/groups,
at 1.7.0/master = /auth/groups; GraphSpaceGroupAPI.java only at master.
Tag 1.0.0 has no api/auth directory at that path, so the wording now names
1.5.x and 1.7.0 rather than generalising over every release.

Not verified: no hugo build here (no hugo, Go 1.26 vs pinned 1.27.0, and
scripts/hugo.sh needs python), so CI is the build check for this text.
---
 content/cn/docs/clients/restful-api/auth.md |  3 ++-
 content/en/docs/clients/restful-api/auth.md | 10 ++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 680eff4d81..951d88e1b0 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -9,7 +9,8 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
 > - 1.7.0+: Auth API 路径使用 GraphSpace 格式，如 `/graphspaces/DEFAULT/auth/users`，且 group/target 等 id 格式与 name 一致（如 `admin`）
 > - 1.5.x 及更早: Auth API 路径包含 graph 名称，group/target 等 id 格式类似 `-69:grant`。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
 >
-> 用户组路径是例外：`GroupAPI` 在所有版本中都挂载于 `/auth/groups`，不带 GraphSpace 前缀；
+> 用户组路径在 1.7.0 上是例外：该版本的 `GroupAPI` 挂载于 `/auth/groups`，不带 GraphSpace 前缀，
+> 而 1.5.x 的用户组路径与其他 Auth API 一样带有 graph 名称（`/graphs/{graph}/auth/groups`）。
 > 下文的 `/graphspaces/{graphspace}/auth/groups` 形式需要包含
 > [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建，晚于 1.7.0 发布版。
 > 在 1.7.0 上带前缀的用户组路径会返回 404。
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index c20333c1b5..b63ad43486 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -9,10 +9,12 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 > - 1.7.0+: Auth API paths use GraphSpace format, such as `/graphspaces/DEFAULT/auth/users`, and group/target IDs match their names (e.g., `admin`)
 > - 1.5.x and earlier: Auth API paths include graph name, and group/target IDs use format like `-69:grant`. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
 >
-> Group paths are the exception: `GroupAPI` is mounted at `/auth/groups` in every
-> version, and the `/graphspaces/{graphspace}/auth/groups` forms below need a build
-> that includes [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096),
-> which is newer than the 1.7.0 release. On 1.7.0 the prefixed group path returns 404.
+> Group paths are the exception in 1.7.0: there `GroupAPI` is served at `/auth/groups`
+> with no GraphSpace prefix, while on 1.5.x it carried the graph name
+> (`/graphs/{graph}/auth/groups`) like the other auth APIs. The
+> `/graphspaces/{graphspace}/auth/groups` forms below need a build that includes
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096), which is newer
+> than the 1.7.0 release. On 1.7.0 the prefixed group path returns 404.
 
 ### 10.1 User Authentication and Access Control
 

From 210b911f98b675eefff95f861482f462645b45e8 Mon Sep 17 00:00:00 2001
From: Adarsh <adarsh@neuroad.ai>
Date: Sat, 26 Sep 2026 00:52:24 +0530
Subject: [PATCH 3/8] docs(auth): correct the group-path status and the scoped
 group id

imbajin's review on #500 flagged two things and both are right.

1. The notice said the prefixed group path "returns 404" on 1.7.0. That
   route is unregistered there, but 404 is not unconditional:
   AuthenticationFilter is @Provider @PreMatching @Priority(AUTHENTICATION),
   so it runs before route matching. Inside authenticate() a missing
   Authorization header throws NotAuthorizedException (401) and an IP
   outside the white list throws ForbiddenException (403); only when
   manager.requireAuthentication() is false does the filter return
   User.ANONYMOUS and leave routing to produce 404. Same code at 1.7.0 and
   at master, so the notice now says unregistered and names the condition.

2. The GraphSpace group examples still carried 1.5.x ids. JsonGroup
   build(graphSpace) persists scopedPrefix(graphSpace) + a dashless UUID,
   where scopedPrefix is "~hubble_role:v1:" + base64url(graphspace) + ":",
   and StandardAuthManagerV2.createGroup assigns id =
   IdGenerator.of(group.name()). A DEFAULT-space group is therefore
   addressed as ~hubble_role:v1:REVGQVVMVA:<32 hex>, and the request's
   group_name is only a client label: build() ignores it while checkCreate()
   requires it non-null. The five group examples now use the generated id,
   and the PUT body drops group_name because build(HugeGroup) rejects any
   other value with "The name of group can't be updated". Mirrored in
   Chinese, as the guide requires.

Left alone deliberately: 10.5 and 10.6 embed the same legacy -69: group id
inside belong/access ids. That is a second pass over two more sections and
is worth its own change rather than being bundled here.

Verified from source through the contents API at ref 1.7.0 and master:
AuthenticationFilter.java, GraphSpaceGroupAPI.java, GroupAPI.java,
StandardAuthManagerV2.java (SCOPED_GROUP_PREFIX, scopedGroupPrefix,
isScopedGroup, createGroup) and HugeGroup.java. base64url("DEFAULT") =
REVGQVVMVA computed rather than guessed, and the example hex is 32 chars to
match isScopedGroup()'s [0-9a-f]{32}.

Executed locally, the one CI step that needs no hugo: python3 -m unittest
discover -s scripts -p 'test_*.py' = 166 tests with 8 failures + 14 errors,
identical failing-name sets at this commit and at pristine HEAD, so this
change is regression-neutral; those 22 are Windows path-separator asserts in
the suite, not this text. dist/validate-links.sh is not trustworthy on this
host (it flags 275 links, including ./auth from graphspace.md, as resolving
outside content/), so the diff was checked differently: it adds and removes
no markdown link syntax at all. Staged blobs re-checked at 0 CR bytes.

Not verified: no hugo build, no Java and no Docker on this host, so no
request was ever issued against a 1.7.0 or master server. The 401/403/404
ordering and the id shape are read from source, not observed.

Refs: https://github.com/apache/hugegraph/issues/3019
---
 content/cn/docs/clients/restful-api/auth.md | 38 +++++++++++--------
 content/en/docs/clients/restful-api/auth.md | 41 +++++++++++++--------
 2 files changed, 49 insertions(+), 30 deletions(-)

diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 951d88e1b0..1d3d81dc43 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -13,7 +13,9 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
 > 而 1.5.x 的用户组路径与其他 Auth API 一样带有 graph 名称（`/graphs/{graph}/auth/groups`）。
 > 下文的 `/graphspaces/{graphspace}/auth/groups` 形式需要包含
 > [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建，晚于 1.7.0 发布版。
-> 在 1.7.0 上带前缀的用户组路径会返回 404。
+> 在 1.7.0 上该路由并未注册，而不是直接返回 404：`AuthenticationFilter` 标注了 `@PreMatching`，
+> 在路由匹配之前执行，开启鉴权时会先返回 401（缺少凭据）或 403（IP 不在白名单内），
+> 只在关闭鉴权时才返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -259,12 +261,18 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 > `GroupAPI` 本身挂载在 `/auth/groups`，不带 GraphSpace 前缀，这也是 1.7.0 上唯一的用户组路径；
 > 下文的 `/graphspaces/DEFAULT/auth/groups` 形式需要包含
 > [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建。
+>
+> 在 GraphSpace 形式下，持久化的用户组名由服务端生成：
+> `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 位十六进制，
+> 因此 `DEFAULT` 中的用户组形如 `~hubble_role:v1:REVGQVVMVA:<32 位十六进制>`，其 `id` 即该值。
+> 请求体中的 `group_name` 仅是客户端标签。下文各请求请使用创建响应返回的 id；
+> `-69:all` 是 1.5.x 的格式，在 GraphSpace 用户组中不标识任何对象。
 
 #### 10.3.1 创建用户组
 
 ##### Params
 
-- group_name: 用户组名称
+- group_name: 仅作为客户端标签 —— GraphSpace 形式下持久化的名称由服务端生成
 - group_description: 用户组描述
 
 ##### Request Body
@@ -294,10 +302,10 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
 ```json
 {
     "group_creator": "admin",
-    "group_name": "all",
+    "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_create": "2020-11-11 15:46:08.791",
     "group_update": "2020-11-11 15:46:08.791",
-    "id": "-69:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_description": "group can do anything"
 }
 ```
@@ -312,7 +320,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -330,14 +338,14 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Request Body
-修改 group_description
+修改 group_description。GraphSpace 形式下这里的 `group_name` 应当省略，或等于服务端生成的名称，
+传入其他值会被拒绝并提示 "The name of group can't be updated"。
 ```json
 {
-    "group_name": "grant",
     "group_description": "grant"
 }
 ```
@@ -353,10 +361,10 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
 ```json
 {
     "group_creator": "admin",
-    "group_name": "grant",
+    "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_create": "2020-11-12 09:50:58.458",
     "group_update": "2020-11-12 09:57:58.155",
-    "id": "-69:grant",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_description": "grant"
 }
 ```
@@ -386,10 +394,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
     "groups": [
         {
             "group_creator": "admin",
-            "group_name": "all",
+            "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
             "group_create": "2020-11-11 15:46:08.791",
             "group_update": "2020-11-11 15:46:08.791",
-            "id": "-69:all",
+            "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
             "group_description": "group can do anything"
         }
     ]
@@ -405,7 +413,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -419,10 +427,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:all
 ```json
 {
     "group_creator": "admin",
-    "group_name": "all",
+    "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_create": "2020-11-11 15:46:08.791",
     "group_update": "2020-11-11 15:46:08.791",
-    "id": "-69:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_description": "group can do anything"
 }
 ```
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index b63ad43486..2ff7441873 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -14,7 +14,10 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 > (`/graphs/{graph}/auth/groups`) like the other auth APIs. The
 > `/graphspaces/{graphspace}/auth/groups` forms below need a build that includes
 > [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096), which is newer
-> than the 1.7.0 release. On 1.7.0 the prefixed group path returns 404.
+> than the 1.7.0 release. On 1.7.0 that route is unregistered rather than 404:
+> `AuthenticationFilter` is `@PreMatching`, so it runs before route matching and answers
+> 401 (no credentials) or 403 (IP outside the white list); 404 comes back only when
+> authentication is disabled.
 
 ### 10.1 User Authentication and Access Control
 
@@ -256,12 +259,19 @@ The group interface includes APIs for creating groups, deleting groups, modifyin
 > `GroupAPI` itself is served at `/auth/groups` with no GraphSpace prefix, and that is
 > the only group path on 1.7.0. The `/graphspaces/DEFAULT/auth/groups` form used below
 > needs a build containing [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096).
+>
+> On the GraphSpace form the server generates the persisted group name:
+> `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 hex digits, so a group in
+> `DEFAULT` is addressed as `~hubble_role:v1:REVGQVVMVA:<32 hex>`, and its `id` is that
+> same value. The request's `group_name` is only a client label. Pass the id returned by
+> the create response to the requests below; the `-69:all` form is the 1.5.x one and
+> identifies no GraphSpace group.
 
 #### 10.3.1 Create Group
 
 ##### Params
 
-- group_name: Group name
+- group_name: Client label only — the GraphSpace API generates the persisted name
 - group_description: Group description
 
 ##### Request Body
@@ -291,10 +301,10 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
 ```json
 {
     "group_creator": "admin",
-    "group_name": "all",
+    "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_create": "2020-11-11 15:46:08.791",
     "group_update": "2020-11-11 15:46:08.791",
-    "id": "-69:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_description": "group can do anything"
 }
 ```
@@ -309,7 +319,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -327,14 +337,15 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Request Body
-Modify group_description
+Modify group_description. On the GraphSpace form `group_name` is omitted here, or equal
+to the generated name: any other value is rejected with "The name of group can't be
+updated".
 ```json
 {
-    "group_name": "grant",
     "group_description": "grant"
 }
 ```
@@ -351,10 +362,10 @@ The returned result is the entire group object including the modified content.
 ```json
 {
     "group_creator": "admin",
-    "group_name": "grant",
+    "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_create": "2020-11-12 09:50:58.458",
     "group_update": "2020-11-12 09:57:58.155",
-    "id": "-69:grant",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_description": "grant"
 }
 ```
@@ -384,10 +395,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
     "groups": [
         {
             "group_creator": "admin",
-            "group_name": "all",
+            "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
             "group_create": "2020-11-11 15:46:08.791",
             "group_update": "2020-11-11 15:46:08.791",
-            "id": "-69:all",
+            "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
             "group_description": "group can do anything"
         }
     ]
@@ -403,7 +414,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -417,10 +428,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:all
 ```json
 {
     "group_creator": "admin",
-    "group_name": "all",
+    "group_name": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_create": "2020-11-11 15:46:08.791",
     "group_update": "2020-11-11 15:46:08.791",
-    "id": "-69:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "group_description": "group can do anything"
 }
 ```

From 494d750234011aba70f5ee63aa883368ab114bd6 Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Sat, 26 Sep 2026 18:10:22 +0800
Subject: [PATCH 4/8] docs(auth): align examples with master

- Clarify version-specific group routes and 404 behavior.

- Use GraphSpace group, target, belong, and access IDs.

- URL-encode composite IDs in relationship paths.

- Keep English and Chinese examples aligned.
---
 content/cn/docs/clients/restful-api/auth.md | 109 ++++++++++---------
 content/en/docs/clients/restful-api/auth.md | 111 +++++++++++---------
 2 files changed, 117 insertions(+), 103 deletions(-)

diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 1d3d81dc43..d7759be1b3 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -6,16 +6,18 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
 ---
 
 > **版本变更说明**:
-> - 1.7.0+: Auth API 路径使用 GraphSpace 格式，如 `/graphspaces/DEFAULT/auth/users`，且 group/target 等 id 格式与 name 一致（如 `admin`）
-> - 1.5.x 及更早: Auth API 路径包含 graph 名称，group/target 等 id 格式类似 `-69:grant`。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+> - 1.7.0+: 图空间范围的 Auth API 路径使用 GraphSpace 格式，如 `/graphspaces/DEFAULT/auth/users`。资源 ID 与资源名一致；GraphSpace 用户组 ID 由服务端生成。用户组路径会因版本而异，见下文。
+> - 1.5.x 及更早: 图范围的 Auth API 路径包含 graph 名称，部分用户组和资源 ID 使用 `-69:grant`、`-77:grant` 这类格式。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
 >
-> 用户组路径在 1.7.0 上是例外：该版本的 `GroupAPI` 挂载于 `/auth/groups`，不带 GraphSpace 前缀，
-> 而 1.5.x 的用户组路径与其他 Auth API 一样带有 graph 名称（`/graphs/{graph}/auth/groups`）。
-> 下文的 `/graphspaces/{graphspace}/auth/groups` 形式需要包含
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建，晚于 1.7.0 发布版。
-> 在 1.7.0 上该路由并未注册，而不是直接返回 404：`AuthenticationFilter` 标注了 `@PreMatching`，
-> 在路由匹配之前执行，开启鉴权时会先返回 401（缺少凭据）或 403（IP 不在白名单内），
-> 只在关闭鉴权时才返回 404。
+> 用户组路径会随版本变化。1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`；
+> 1.5.x 使用 `/graphs/{graph}/auth/groups`。下文的 GraphSpace 路径
+> `/graphspaces/{graphspace}/auth/groups` 由
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 在 1.7.0 发布后加入，
+> 在当前 `master` 中与 `/auth/groups` 并存。
+>
+> 在 1.7.0 上，GraphSpace 路由未注册。`AuthenticationFilter` 标注了 `@PreMatching`，
+> 会在路由匹配前执行：缺少或无效凭据可能返回 401，IP 不在白名单内可能返回 403。
+> 如果过滤器接受请求，后续路由匹配会因该路径未注册而返回 404；关闭鉴权时也可能返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -35,7 +37,7 @@ city: Beijing})
 
 ##### 接口说明：
 用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。
-**注意**: 1.5.0 及之前，group/target 等 id 的格式类似 -69:grant，1.7.0 及之后，id 和 name 一致，如 admin [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+**注意**: 1.5.x 及更早版本中的部分用户组和资源 ID 使用 `-69:grant`、`-77:grant` 这类格式。GraphSpace 用户组 ID 由服务端生成，见下文。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
 
 ### 10.2 用户（User）API
 用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。
@@ -258,9 +260,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。  
 用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。  
 
-> `GroupAPI` 本身挂载在 `/auth/groups`，不带 GraphSpace 前缀，这也是 1.7.0 上唯一的用户组路径；
-> 下文的 `/graphspaces/DEFAULT/auth/groups` 形式需要包含
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 的构建。
+> `GroupAPI` 仍挂载在 `/auth/groups`。这是 1.7.0 上唯一的用户组路由；下文的
+> `/graphspaces/DEFAULT/auth/groups` 由
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 加入，当前 `master`
+> 同时提供这两种路径。
 >
 > 在 GraphSpace 形式下，持久化的用户组名由服务端生成：
 > `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 位十六进制，
@@ -501,7 +504,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
             "properties": null
         }
     ],
-    "id": "-77:all",
+    "id": "all",
     "target_update": "2020-11-11 15:32:01.192"
 }
 ```
@@ -516,7 +519,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/gremlin
 ```
 
 ##### Response Status
@@ -535,7 +538,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/gremlin
 ```
 
 ##### Request Body
@@ -575,7 +578,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
             "properties": null
         }
     ],
-    "id": "-77:gremlin",
+    "id": "gremlin",
     "target_update": "2020-11-12 09:37:12.780"
 }
 ```
@@ -616,7 +619,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
                     "properties": null
                 }
             ],
-            "id": "-77:all",
+            "id": "all",
             "target_update": "2020-11-11 15:32:01.192"
         },
         {
@@ -632,7 +635,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
                     "properties": null
                 }
             ],
-            "id": "-77:grant",
+            "id": "grant",
             "target_update": "2020-11-11 15:43:24.841"
         }
     ]
@@ -648,7 +651,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
+GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 ```
 
 ##### Response Status
@@ -673,7 +676,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
             "properties": null
         }
     ],
-    "id": "-77:grant",
+    "id": "grant",
     "target_update": "2020-11-11 15:43:24.841"
 }
 ```
@@ -682,6 +685,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
 关联用户和用户组的关系，一个用户可以关联一个或者多个用户组。用户组拥有相关资源的权限，不同用户组的资源权限可以理解为不同的角色。即给用户关联角色。  
 关联角色接口包括：用户关联角色的创建、删除、修改和查询。
 
+> 下例中的用户组 ID 沿用 10.3 的示例返回值；实际调用时请使用自己创建响应中的 ID。后续请求请使用创建关联关系时返回的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
+
 #### 10.5.1 创建用户的关联角色
 
 ##### Params
@@ -695,7 +700,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
 ```json
 {
   "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -719,9 +724,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
     "belong_create": "2020-11-11 16:19:35.422",
     "belong_creator": "admin",
     "belong_update": "2020-11-11 16:19:35.422",
-  "id": "Sboss>-82>>S-69:all",
+  "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
   "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -734,7 +739,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -753,7 +758,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:gr
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Request Body
@@ -778,9 +783,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
     "belong_create": "2020-11-12 10:40:21.720",
     "belong_creator": "admin",
     "belong_update": "2020-11-12 10:42:47.265",
-  "id": "Sboss>-82>>S-69:grant",
+  "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
   "user": "boss",
-    "group": "-69:grant"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -816,9 +821,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
             "belong_create": "2020-11-11 16:19:35.422",
             "belong_creator": "admin",
             "belong_update": "2020-11-11 16:19:35.422",
-          "id": "Sboss>-82>>S-69:all",
+          "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
           "user": "boss",
-            "group": "-69:all"
+            "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
         }
     ]
 }
@@ -833,7 +838,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -849,9 +854,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
     "belong_create": "2020-11-11 16:19:35.422",
     "belong_creator": "admin",
     "belong_update": "2020-11-11 16:19:35.422",
-  "id": "Sboss>-82>>S-69:all",
+  "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
   "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -859,6 +864,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
 给用户组赋予资源的权限，主要包含：读操作 (READ)、写操作 (WRITE)、删除操作 (DELETE)、执行操作 (EXECUTE) 等。  
 赋权接口包括：赋权的创建、删除、修改和查询。
 
+> 下例沿用 10.3 创建的用户组 ID 和 10.4 创建的资源 ID。实际调用时请使用各自创建响应中的 ID；用户组 ID 由服务端生成。后续请求请复制创建赋权响应中的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
+
 #### 10.6.1 创建赋权 (用户组赋予资源的权限)
 
 ##### Params
@@ -878,8 +885,8 @@ access_permission：
 
 ```json
 {
-    "group": "-69:all",
-    "target": "-77:all",
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all",
     "access_permission": "READ"
 }
 ```
@@ -902,11 +909,11 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 {
     "access_permission": "READ",
     "access_create": "2020-11-11 15:54:54.008",
-    "id": "S-69:all>-88>11>S-77:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
     "access_update": "2020-11-11 15:54:54.008",
     "access_creator": "admin",
-    "group": "-69:all",
-    "target": "-77:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all"
 }
 ```
 
@@ -920,7 +927,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77:all
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
 ```
 
 ##### Response Status
@@ -939,7 +946,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77:all
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
 ```
 
 ##### Request Body
@@ -961,13 +968,13 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77
 ```json
 {
     "access_description": "test",
-    "access_permission": "WRITE",
+    "access_permission": "READ",
     "access_create": "2020-11-12 10:12:03.074",
-    "id": "S-69:all>-88>12>S-77:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
     "access_update": "2020-11-12 10:16:18.637",
     "access_creator": "admin",
-    "group": "-69:all",
-    "target": "-77:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all"
 }
 ```
 
@@ -1001,11 +1008,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
         {
             "access_permission": "READ",
             "access_create": "2020-11-11 15:54:54.008",
-            "id": "S-69:all>-88>11>S-77:all",
+            "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
             "access_update": "2020-11-11 15:54:54.008",
             "access_creator": "admin",
-            "group": "-69:all",
-            "target": "-77:all"
+            "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+            "target": "all"
         }
     ]
 }
@@ -1020,7 +1027,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
 ```
 
 ##### Response Status
@@ -1035,11 +1042,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77
 {
     "access_permission": "READ",
     "access_create": "2020-11-11 15:54:54.008",
-    "id": "S-69:all>-88>11>S-77:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
     "access_update": "2020-11-11 15:54:54.008",
     "access_creator": "admin",
-    "group": "-69:all",
-    "target": "-77:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all"
 }
 ```
 
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index 2ff7441873..7c2b30fd13 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -6,17 +6,19 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 ---
 
 > **Version Change Notice**:
-> - 1.7.0+: Auth API paths use GraphSpace format, such as `/graphspaces/DEFAULT/auth/users`, and group/target IDs match their names (e.g., `admin`)
-> - 1.5.x and earlier: Auth API paths include graph name, and group/target IDs use format like `-69:grant`. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+> - 1.7.0+: GraphSpace-scoped Auth API paths use the GraphSpace format, such as `/graphspaces/DEFAULT/auth/users`. Target IDs match their names; GraphSpace group IDs are generated by the server. Group routes vary by version; see below.
+> - 1.5.x and earlier: Graph-scoped Auth API paths include the graph name, and some group/target IDs use forms such as `-69:grant` and `-77:grant`. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
 >
-> Group paths are the exception in 1.7.0: there `GroupAPI` is served at `/auth/groups`
-> with no GraphSpace prefix, while on 1.5.x it carried the graph name
-> (`/graphs/{graph}/auth/groups`) like the other auth APIs. The
-> `/graphspaces/{graphspace}/auth/groups` forms below need a build that includes
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096), which is newer
-> than the 1.7.0 release. On 1.7.0 that route is unregistered rather than 404:
-> `AuthenticationFilter` is `@PreMatching`, so it runs before route matching and answers
-> 401 (no credentials) or 403 (IP outside the white list); 404 comes back only when
+> Group routes vary by version. On 1.7.0, `GroupAPI` is served at `/auth/groups`;
+> on 1.5.x it used `/graphs/{graph}/auth/groups`. The GraphSpace route
+> `/graphspaces/{graphspace}/auth/groups` below was added by
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) after 1.7.0
+> and coexists with `/auth/groups` on current `master`.
+>
+> On 1.7.0 the GraphSpace route is unregistered. `AuthenticationFilter` is `@PreMatching`,
+> so it runs before route matching: missing or invalid credentials can return 401, and an
+> IP outside the white list can return 403. If the filter accepts the request, route
+> matching continues and returns 404 for this unregistered path; 404 can also occur when
 > authentication is disabled.
 
 ### 10.1 User Authentication and Access Control
@@ -32,7 +34,7 @@ Description: User 'boss' has read permission for people in the 'graph1' graph fr
 
 ##### Interface Description:
 The core of user authentication and access control is 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI. Alongside them, ManagerAPI grants graphspace-level manager roles, LoginAPI issues and verifies tokens, and ProjectAPI groups several graphs so that permissions can be granted for the whole set at once.
-**Note** Before 1.5.0, the format of ids such as group/target was similar to -69:grant. After 1.7.0, the id and name were consistent. Such as admin [HugeGraph 1.5 x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+**Note** Some group and target IDs in 1.5.x and earlier use forms such as `-69:grant` and `-77:grant`. GraphSpace group IDs are generated by the server, as described below. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
 
 ### 10.2 User (User) API
 The user interface includes APIs for creating users, deleting users, modifying users, and querying user-related information.
@@ -256,9 +258,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 Groups grant corresponding resource permissions, and users are assigned to different groups, thereby having different resource permissions.
 The group interface includes APIs for creating groups, deleting groups, modifying groups, and querying group-related information.
 
-> `GroupAPI` itself is served at `/auth/groups` with no GraphSpace prefix, and that is
-> the only group path on 1.7.0. The `/graphspaces/DEFAULT/auth/groups` form used below
-> needs a build containing [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096).
+> `GroupAPI` remains available at `/auth/groups`. That is the only group route on 1.7.0;
+> the `/graphspaces/DEFAULT/auth/groups` form used below was added by
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) and is available
+> alongside `/auth/groups` on current `master`.
 >
 > On the GraphSpace form the server generates the persisted group name:
 > `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 hex digits, so a group in
@@ -500,7 +503,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
             "properties": null
         }
     ],
-    "id": "-77:all",
+    "id": "all",
     "target_update": "2020-11-11 15:32:01.192"
 }
 ```
@@ -514,7 +517,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/gremlin
 ```
 
 ##### Response Status
@@ -532,7 +535,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/gremlin
 ```
 
 ##### Request Body
@@ -573,7 +576,7 @@ The response contains the entire target group object, including the modified con
             "properties": null
         }
     ],
-    "id": "-77:gremlin",
+    "id": "gremlin",
     "target_update": "2020-11-12 09:37:12.780"
 }
 ```
@@ -614,7 +617,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
                     "properties": null
                 }
             ],
-            "id": "-77:all",
+            "id": "all",
             "target_update": "2020-11-11 15:32:01.192"
         },
         {
@@ -630,7 +633,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
                     "properties": null
                 }
             ],
-            "id": "-77:grant",
+            "id": "grant",
             "target_update": "2020-11-11 15:43:24.841"
         }
     ]
@@ -646,7 +649,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
+GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 ```
 
 ##### Response Status
@@ -671,7 +674,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
             "properties": null
         }
     ],
-    "id": "-77:grant",
+    "id": "grant",
     "target_update": "2020-11-11 15:43:24.841"
 }
 ```
@@ -681,6 +684,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
 The association between users and user groups allows a user to be associated with one or more user groups. User groups have permissions for related resources, and the permissions for different user groups can be understood as different roles. In other words, users are associated with roles.  
 The API for associating roles includes creating, deleting, modifying, and querying the association of roles for users.
 
+> The group ID below reuses the example returned in 10.3; use the ID from your own create response. For later requests, copy the `id` returned by the create-belong response and URL-encode `>` as `%3E` in the path.
+
 #### 10.5.1 Create an Association of Roles for a User
 
 ##### Params
@@ -694,7 +699,7 @@ The API for associating roles includes creating, deleting, modifying, and queryi
 ```json
 {
     "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -718,9 +723,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
     "belong_create": "2020-11-11 16:19:35.422",
     "belong_creator": "admin",
     "belong_update": "2020-11-11 16:19:35.422",
-    "id": "Sboss>-82>>S-69:all",
+    "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -733,7 +738,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -753,7 +758,7 @@ An association of roles can only be modified for its description. The `user` and
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Request Body
@@ -778,9 +783,9 @@ The response includes the modified content as well as the entire association of
     "belong_create": "2020-11-12 10:40:21.720",
     "belong_creator": "admin",
     "belong_update": "2020-11-12 10:42:47.265",
-    "id": "Sboss>-82>>S-69:grant",
+    "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "user": "boss",
-    "group": "-69:grant"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -816,9 +821,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
             "belong_create": "2020-11-11 16:19:35.422",
             "belong_creator": "admin",
             "belong_update": "2020-11-11 16:19:35.422",
-            "id": "Sboss>-82>>S-69:all",
+            "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
             "user": "boss",
-            "group": "-69:all"
+            "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
         }
     ]
 }
@@ -833,7 +838,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
 ```
 
 ##### Response Status
@@ -849,9 +854,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
     "belong_create": "2020-11-11 16:19:35.422",
     "belong_creator": "admin",
     "belong_update": "2020-11-11 16:19:35.422",
-    "id": "Sboss>-82>>S-69:all",
+    "id": "boss->ug->~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
     "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -859,6 +864,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
 Grant permissions to user groups for resources, including operations such as READ, WRITE, DELETE, EXECUTE, etc.
 The authorization API includes: creating, deleting, modifying, and querying permissions.
 
+> The examples reuse the group ID from 10.3 and target ID from 10.4. Use the IDs returned by your own create responses; the group ID is generated by the server. For later requests, copy the access `id` from the create response and URL-encode `>` as `%3E` in the path.
+
 #### 10.6.1 Create Authorization (Granting permissions to user groups for resources)
 
 ##### Params
@@ -878,8 +885,8 @@ Access permissions:
 
 ```json
 {
-    "group": "-69:all",
-    "target": "-77:all",
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all",
     "access_permission": "READ"
 }
 ```
@@ -902,11 +909,11 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 {
     "access_permission": "READ",
     "access_create": "2020-11-11 15:54:54.008",
-    "id": "S-69:all>-88>11>S-77:all",
+    "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
     "access_update": "2020-11-11 15:54:54.008",
     "access_creator": "admin",
-  "group": "-69:all",
-  "target": "-77:all"
+  "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+  "target": "all"
 }
 ```
 
@@ -919,7 +926,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77:all
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
 ```
 
 ##### Response Status
@@ -939,7 +946,7 @@ Authorization can only be modified for its description. User group, resource, an
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77:all
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
 ```
 
 ##### Request Body
@@ -965,13 +972,13 @@ The response includes the modified content as well as the entire authorization o
 ```json
 {
   "access_description": "test",
-  "access_permission": "WRITE",
+  "access_permission": "READ",
   "access_create": "2020-11-12 10:12:03.074",
-  "id": "S-69:all>-88>12>S-77:all",
+  "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
   "access_update": "2020-11-12 10:16:18.637",
   "access_creator": "admin",
-  "group": "-69:all",
-  "target": "-77:all"
+  "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+  "target": "all"
 }
 ```
 
@@ -1005,11 +1012,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
     {
       "access_permission": "READ",
       "access_create": "2020-11-11 15:54:54.008",
-      "id": "S-69:all>-88>11>S-77:all",
+      "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
       "access_update": "2020-11-11 15:54:54.008",
       "access_creator": "admin",
-      "group": "-69:all",
-      "target": "-77:all"
+      "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+      "target": "all"
     }
   ]
 }
@@ -1024,7 +1031,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
 ```
 
 ##### Response Status
@@ -1039,11 +1046,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77
 {
   "access_permission": "READ",
   "access_create": "2020-11-11 15:54:54.008",
-  "id": "S-69:all>-88>11>S-77:all",
+  "id": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94->1->all",
   "access_update": "2020-11-11 15:54:54.008",
   "access_creator": "admin",
-    "group": "-69:all",
-    "target": "-77:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all"
 }
 ```
 

From 946e95e885f38766b800443f24ff768a21769a06 Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Sat, 26 Sep 2026 18:25:00 +0800
Subject: [PATCH 5/8] docs(auth): apply 120-character markdown limit

- Set the Markdown editor line limit to 120 characters.

- Reflow changed English and Chinese documentation lines.

- Use response-ID placeholders for long relationship paths.

- Record the Markdown line-length rule in AGENTS.md.
---
 .editorconfig                               |  2 +-
 AGENTS.md                                   |  3 ++
 content/cn/docs/clients/restful-api/auth.md | 30 ++++++++++------
 content/en/docs/clients/restful-api/auth.md | 39 ++++++++++++++-------
 4 files changed, 49 insertions(+), 25 deletions(-)

diff --git a/.editorconfig b/.editorconfig
index fa6c64db75..d6f11ba984 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -31,4 +31,4 @@ indent_size = 4
 continuation_indent_size = 8
 
 [*.md]
-max_line_length = off
+max_line_length = 120
diff --git a/AGENTS.md b/AGENTS.md
index 6e89817082..ca3efdee92 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,9 @@ upgrade or deployment workflow. Use `go.mod` / `go.sum` and CI for pinned versio
 ## Project constraints
 
 - Keep English and Chinese documentation aligned when a change applies to both.
+- Keep edited Markdown lines within 120 characters; `.editorconfig` sets the
+  editor limit. Wrap prose at word boundaries and use placeholders for long,
+  generated IDs in URL examples.
 - Preserve public routes, historical-version navigation and language switching.
 - Keep HugeGraph branding and behavior in site configuration, data, hooks and
   public OINK APIs. Do not edit the module cache or vendor a theme fork.
diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index d7759be1b3..d8969e0982 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -6,8 +6,12 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
 ---
 
 > **版本变更说明**:
-> - 1.7.0+: 图空间范围的 Auth API 路径使用 GraphSpace 格式，如 `/graphspaces/DEFAULT/auth/users`。资源 ID 与资源名一致；GraphSpace 用户组 ID 由服务端生成。用户组路径会因版本而异，见下文。
-> - 1.5.x 及更早: 图范围的 Auth API 路径包含 graph 名称，部分用户组和资源 ID 使用 `-69:grant`、`-77:grant` 这类格式。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+> - 1.7.0+: 图空间范围的 Auth API 使用 GraphSpace 路径，如
+>   `/graphspaces/DEFAULT/auth/users`。资源 ID 与名称一致，GraphSpace 用户组 ID
+>   由服务端生成。用户组路径会因版本而异，见下文。
+> - 1.5.x 及更早：图范围 Auth API 路径包含 graph 名称；部分用户组和资源 ID
+>   使用 `-69:grant`、`-77:grant` 这类格式。参考
+>   [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
 >
 > 用户组路径会随版本变化。1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`；
 > 1.5.x 使用 `/graphs/{graph}/auth/groups`。下文的 GraphSpace 路径
@@ -37,7 +41,9 @@ city: Beijing})
 
 ##### 接口说明：
 用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。
-**注意**: 1.5.x 及更早版本中的部分用户组和资源 ID 使用 `-69:grant`、`-77:grant` 这类格式。GraphSpace 用户组 ID 由服务端生成，见下文。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
+**注意**: 1.5.x 及更早版本中的部分用户组和资源 ID 使用
+`-69:grant`、`-77:grant` 这类格式。GraphSpace 用户组 ID 由服务端生成，见下文。
+参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
 
 ### 10.2 用户（User）API
 用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。
@@ -685,7 +691,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 关联用户和用户组的关系，一个用户可以关联一个或者多个用户组。用户组拥有相关资源的权限，不同用户组的资源权限可以理解为不同的角色。即给用户关联角色。  
 关联角色接口包括：用户关联角色的创建、删除、修改和查询。
 
-> 下例中的用户组 ID 沿用 10.3 的示例返回值；实际调用时请使用自己创建响应中的 ID。后续请求请使用创建关联关系时返回的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
+> 下例中的用户组 ID 沿用 10.3 的示例返回值，实际调用时请使用自己创建响应中的 ID。
+> 后续请求请使用创建关联关系响应中的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
 
 #### 10.5.1 创建用户的关联角色
 
@@ -739,7 +746,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 ```
 
 ##### Response Status
@@ -758,7 +765,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hub
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 ```
 
 ##### Request Body
@@ -838,7 +845,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
+GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 ```
 
 ##### Response Status
@@ -864,7 +871,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble
 给用户组赋予资源的权限，主要包含：读操作 (READ)、写操作 (WRITE)、删除操作 (DELETE)、执行操作 (EXECUTE) 等。  
 赋权接口包括：赋权的创建、删除、修改和查询。
 
-> 下例沿用 10.3 创建的用户组 ID 和 10.4 创建的资源 ID。实际调用时请使用各自创建响应中的 ID；用户组 ID 由服务端生成。后续请求请复制创建赋权响应中的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
+> 下例沿用 10.3 创建的用户组 ID 和 10.4 创建的资源 ID。实际调用时请使用各自创建响应中的 ID；
+> 用户组 ID 由服务端生成。后续请求请复制创建赋权响应中的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
 
 #### 10.6.1 创建赋权 (用户组赋予资源的权限)
 
@@ -927,7 +935,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
 ```
 
 ##### Response Status
@@ -946,7 +954,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:R
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
 ```
 
 ##### Request Body
@@ -1027,7 +1035,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
+GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
 ```
 
 ##### Response Status
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index 7c2b30fd13..3355f0da88 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -6,8 +6,12 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 ---
 
 > **Version Change Notice**:
-> - 1.7.0+: GraphSpace-scoped Auth API paths use the GraphSpace format, such as `/graphspaces/DEFAULT/auth/users`. Target IDs match their names; GraphSpace group IDs are generated by the server. Group routes vary by version; see below.
-> - 1.5.x and earlier: Graph-scoped Auth API paths include the graph name, and some group/target IDs use forms such as `-69:grant` and `-77:grant`. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+> - 1.7.0+: GraphSpace-scoped Auth API paths use the GraphSpace format, such as
+>   `/graphspaces/DEFAULT/auth/users`. Target IDs match their names; GraphSpace
+>   group IDs are generated by the server. Group routes vary by version; see below.
+> - 1.5.x and earlier: Graph-scoped Auth API paths include the graph name. Some
+>   group/target IDs use forms such as `-69:grant` and `-77:grant`. See
+>   [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
 >
 > Group routes vary by version. On 1.7.0, `GroupAPI` is served at `/auth/groups`;
 > on 1.5.x it used `/graphs/{graph}/auth/groups`. The GraphSpace route
@@ -34,7 +38,9 @@ Description: User 'boss' has read permission for people in the 'graph1' graph fr
 
 ##### Interface Description:
 The core of user authentication and access control is 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI. Alongside them, ManagerAPI grants graphspace-level manager roles, LoginAPI issues and verifies tokens, and ProjectAPI groups several graphs so that permissions can be granted for the whole set at once.
-**Note** Some group and target IDs in 1.5.x and earlier use forms such as `-69:grant` and `-77:grant`. GraphSpace group IDs are generated by the server, as described below. See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
+**Note** In 1.5.x and earlier, some group and target IDs use forms such as
+`-69:grant` and `-77:grant`. GraphSpace group IDs are server-generated; see below.
+See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
 
 ### 10.2 User (User) API
 The user interface includes APIs for creating users, deleting users, modifying users, and querying user-related information.
@@ -682,9 +688,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 ### 10.5 Association of Roles (Belong) API
 
 The association between users and user groups allows a user to be associated with one or more user groups. User groups have permissions for related resources, and the permissions for different user groups can be understood as different roles. In other words, users are associated with roles.  
-The API for associating roles includes creating, deleting, modifying, and querying the association of roles for users.
+The API for associating roles includes creating, deleting, modifying, and
+querying the association of roles for users.
 
-> The group ID below reuses the example returned in 10.3; use the ID from your own create response. For later requests, copy the `id` returned by the create-belong response and URL-encode `>` as `%3E` in the path.
+> The group ID below repeats the example from 10.3. Use the ID from your own
+> create response. For later requests, copy the `id` returned by the
+> create-belong response and URL-encode `>` as `%3E` in the path.
 
 #### 10.5.1 Create an Association of Roles for a User
 
@@ -738,7 +747,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 ```
 
 ##### Response Status
@@ -758,7 +767,7 @@ An association of roles can only be modified for its description. The `user` and
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 ```
 
 ##### Request Body
@@ -838,7 +847,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94
+GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 ```
 
 ##### Response Status
@@ -862,9 +871,13 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/boss-%3Eug-%3E~hubble
 
 ### 10.6 Authorization (Access) API
 Grant permissions to user groups for resources, including operations such as READ, WRITE, DELETE, EXECUTE, etc.
-The authorization API includes: creating, deleting, modifying, and querying permissions.
+The authorization API includes: creating, deleting, modifying, and querying
+permissions.
 
-> The examples reuse the group ID from 10.3 and target ID from 10.4. Use the IDs returned by your own create responses; the group ID is generated by the server. For later requests, copy the access `id` from the create response and URL-encode `>` as `%3E` in the path.
+> The examples reuse the group ID from 10.3 and target ID from 10.4. Use the IDs
+> returned by your own create responses; the group ID is generated by the server.
+> For later requests, copy the access `id` from the create response and
+> URL-encode `>` as `%3E` in the path.
 
 #### 10.6.1 Create Authorization (Granting permissions to user groups for resources)
 
@@ -926,7 +939,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
 ```
 
 ##### Response Status
@@ -946,7 +959,7 @@ Authorization can only be modified for its description. User group, resource, an
 ##### Method & Url
 
 ```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
 ```
 
 ##### Request Body
@@ -1031,7 +1044,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
 ##### Method & Url
 
 ```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94-%3E1-%3Eall
+GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
 ```
 
 ##### Response Status

From e0f15ca146577b97b9d8c87bbbdfd981d88f3705 Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Sat, 26 Sep 2026 18:35:55 +0800
Subject: [PATCH 6/8] docs(auth): revise markdown wrapping guidance

- Leave the repository Markdown line width unset.

- Set new prose guidance to 160 characters in AGENTS.md.

- Keep existing one-line paragraphs intact and tighten new notes.

- Use response-ID placeholders for generated relationship paths.
---
 .editorconfig                               |  2 +-
 AGENTS.md                                   |  4 +-
 content/cn/docs/clients/restful-api/auth.md | 44 +++++-----------
 content/en/docs/clients/restful-api/auth.md | 57 ++++++---------------
 4 files changed, 33 insertions(+), 74 deletions(-)

diff --git a/.editorconfig b/.editorconfig
index d6f11ba984..fa6c64db75 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -31,4 +31,4 @@ indent_size = 4
 continuation_indent_size = 8
 
 [*.md]
-max_line_length = 120
+max_line_length = off
diff --git a/AGENTS.md b/AGENTS.md
index ca3efdee92..7d310e85fa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,9 +21,7 @@ upgrade or deployment workflow. Use `go.mod` / `go.sum` and CI for pinned versio
 ## Project constraints
 
 - Keep English and Chinese documentation aligned when a change applies to both.
-- Keep edited Markdown lines within 120 characters; `.editorconfig` sets the
-  editor limit. Wrap prose at word boundaries and use placeholders for long,
-  generated IDs in URL examples.
+- Wrap new Markdown prose at 160 characters; preserve existing one-line paragraphs and use placeholders for generated IDs.
 - Preserve public routes, historical-version navigation and language switching.
 - Keep HugeGraph branding and behavior in site configuration, data, hooks and
   public OINK APIs. Do not edit the module cache or vendor a theme fork.
diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index d8969e0982..2316b2a418 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -6,22 +6,14 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
 ---
 
 > **版本变更说明**:
-> - 1.7.0+: 图空间范围的 Auth API 使用 GraphSpace 路径，如
->   `/graphspaces/DEFAULT/auth/users`。资源 ID 与名称一致，GraphSpace 用户组 ID
->   由服务端生成。用户组路径会因版本而异，见下文。
-> - 1.5.x 及更早：图范围 Auth API 路径包含 graph 名称；部分用户组和资源 ID
->   使用 `-69:grant`、`-77:grant` 这类格式。参考
->   [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
+> - 1.7.0+: 图空间范围的 Auth API 使用 GraphSpace 路径；资源 ID 与名称一致，GraphSpace 用户组 ID 由服务端生成。
+> - 1.5.x 及更早：图范围 Auth API 路径包含 graph 名称；部分用户组/资源 ID 使用旧格式，见 [1.5.x API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
 >
-> 用户组路径会随版本变化。1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`；
-> 1.5.x 使用 `/graphs/{graph}/auth/groups`。下文的 GraphSpace 路径
-> `/graphspaces/{graphspace}/auth/groups` 由
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 在 1.7.0 发布后加入，
-> 在当前 `master` 中与 `/auth/groups` 并存。
+> 1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`，1.5.x 使用 `/graphs/{graph}/auth/groups`。GraphSpace 用户组路由由
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 在 1.7.0 后加入，并与当前 `master` 的 `/auth/groups` 并存。
 >
-> 在 1.7.0 上，GraphSpace 路由未注册。`AuthenticationFilter` 标注了 `@PreMatching`，
-> 会在路由匹配前执行：缺少或无效凭据可能返回 401，IP 不在白名单内可能返回 403。
-> 如果过滤器接受请求，后续路由匹配会因该路径未注册而返回 404；关闭鉴权时也可能返回 404。
+> 1.7.0 上 GraphSpace 路由未注册。`AuthenticationFilter` 标注了 `@PreMatching`，会在路由匹配前执行：缺少或无效凭据
+> 可能返回 401；IP 白名单拒绝可能返回 403。过滤器接受请求后，未匹配的路径返回 404；关闭鉴权时也可能返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -41,9 +33,7 @@ city: Beijing})
 
 ##### 接口说明：
 用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。
-**注意**: 1.5.x 及更早版本中的部分用户组和资源 ID 使用
-`-69:grant`、`-77:grant` 这类格式。GraphSpace 用户组 ID 由服务端生成，见下文。
-参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
+**注意**: 1.5.x 及更早版本中的用户组/资源 ID 使用 `-69:grant`、`-77:grant` 等旧格式；GraphSpace 用户组 ID 由服务端生成。
 
 ### 10.2 用户（User）API
 用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。
@@ -266,16 +256,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。  
 用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。  
 
-> `GroupAPI` 仍挂载在 `/auth/groups`。这是 1.7.0 上唯一的用户组路由；下文的
-> `/graphspaces/DEFAULT/auth/groups` 由
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 加入，当前 `master`
-> 同时提供这两种路径。
+> `GroupAPI` 仍挂载在 `/auth/groups`，这是 1.7.0 上唯一的用户组路由。`/graphspaces/DEFAULT/auth/groups` 由
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 加入，当前 `master` 同时提供这两种路径。
 >
-> 在 GraphSpace 形式下，持久化的用户组名由服务端生成：
-> `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 位十六进制，
-> 因此 `DEFAULT` 中的用户组形如 `~hubble_role:v1:REVGQVVMVA:<32 位十六进制>`，其 `id` 即该值。
-> 请求体中的 `group_name` 仅是客户端标签。下文各请求请使用创建响应返回的 id；
-> `-69:all` 是 1.5.x 的格式，在 GraphSpace 用户组中不标识任何对象。
+> GraphSpace 用户组名由服务端按 `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 位十六进制生成。
+> `DEFAULT` 中的名称和 ID 形如 `~hubble_role:v1:REVGQVVMVA:<32 hex>`；`group_name` 仅是客户端标签。下文请使用
+> 创建响应中的 ID；`-69:all` 是 1.5.x 格式，不能标识 GraphSpace 用户组。
 
 #### 10.3.1 创建用户组
 
@@ -691,8 +677,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 关联用户和用户组的关系，一个用户可以关联一个或者多个用户组。用户组拥有相关资源的权限，不同用户组的资源权限可以理解为不同的角色。即给用户关联角色。  
 关联角色接口包括：用户关联角色的创建、删除、修改和查询。
 
-> 下例中的用户组 ID 沿用 10.3 的示例返回值，实际调用时请使用自己创建响应中的 ID。
-> 后续请求请使用创建关联关系响应中的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
+> 用户组 ID 沿用 10.3 示例；实际调用时请使用自己的响应 ID。后续请求使用 Belong 响应中的 `id`，并将 URL 中的 `>` 编码为 `%3E`。
 
 #### 10.5.1 创建用户的关联角色
 
@@ -871,8 +856,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 给用户组赋予资源的权限，主要包含：读操作 (READ)、写操作 (WRITE)、删除操作 (DELETE)、执行操作 (EXECUTE) 等。  
 赋权接口包括：赋权的创建、删除、修改和查询。
 
-> 下例沿用 10.3 创建的用户组 ID 和 10.4 创建的资源 ID。实际调用时请使用各自创建响应中的 ID；
-> 用户组 ID 由服务端生成。后续请求请复制创建赋权响应中的 `id`，并在 URL 路径中将 `>` 编码为 `%3E`。
+> 使用 10.3 返回的用户组 ID 和 10.4 返回的资源 ID；实际调用时请使用自己的响应值。后续请求使用 Access 响应中的 `id`，并将 URL 中的 `>` 编码为 `%3E`。
 
 #### 10.6.1 创建赋权 (用户组赋予资源的权限)
 
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index 3355f0da88..f8e84c1bb9 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -6,24 +6,15 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 ---
 
 > **Version Change Notice**:
-> - 1.7.0+: GraphSpace-scoped Auth API paths use the GraphSpace format, such as
->   `/graphspaces/DEFAULT/auth/users`. Target IDs match their names; GraphSpace
->   group IDs are generated by the server. Group routes vary by version; see below.
-> - 1.5.x and earlier: Graph-scoped Auth API paths include the graph name. Some
->   group/target IDs use forms such as `-69:grant` and `-77:grant`. See
->   [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
+> - 1.7.0+: GraphSpace-scoped Auth paths use `/graphspaces/{graphspace}/auth/...`; target IDs match names, while GraphSpace group IDs are server-generated.
+> - 1.5.x and earlier: Graph-scoped Auth paths include the graph name; see [1.5.x REST API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
 >
-> Group routes vary by version. On 1.7.0, `GroupAPI` is served at `/auth/groups`;
-> on 1.5.x it used `/graphs/{graph}/auth/groups`. The GraphSpace route
-> `/graphspaces/{graphspace}/auth/groups` below was added by
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) after 1.7.0
-> and coexists with `/auth/groups` on current `master`.
+> On 1.7.0, `GroupAPI` is `/auth/groups`; 1.5.x used `/graphs/{graph}/auth/groups`. The GraphSpace route was added by
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) after 1.7.0 and coexists with `/auth/groups` on `master`.
 >
-> On 1.7.0 the GraphSpace route is unregistered. `AuthenticationFilter` is `@PreMatching`,
-> so it runs before route matching: missing or invalid credentials can return 401, and an
-> IP outside the white list can return 403. If the filter accepts the request, route
-> matching continues and returns 404 for this unregistered path; 404 can also occur when
-> authentication is disabled.
+> On 1.7.0 the GraphSpace route is unregistered. `AuthenticationFilter` is `@PreMatching`, so it runs before route matching:
+> missing or invalid credentials can return 401; an IP outside the white list can return 403. If the filter accepts the
+> request, the unmatched path returns 404. A 404 can also occur when authentication is disabled.
 
 ### 10.1 User Authentication and Access Control
 
@@ -38,9 +29,7 @@ Description: User 'boss' has read permission for people in the 'graph1' graph fr
 
 ##### Interface Description:
 The core of user authentication and access control is 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI. Alongside them, ManagerAPI grants graphspace-level manager roles, LoginAPI issues and verifies tokens, and ProjectAPI groups several graphs so that permissions can be granted for the whole set at once.
-**Note** In 1.5.x and earlier, some group and target IDs use forms such as
-`-69:grant` and `-77:grant`. GraphSpace group IDs are server-generated; see below.
-See [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
+**Note** Legacy 1.5.x group/target IDs include `-69:grant` and `-77:grant`; GraphSpace group IDs are server-generated.
 
 ### 10.2 User (User) API
 The user interface includes APIs for creating users, deleting users, modifying users, and querying user-related information.
@@ -264,17 +253,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 Groups grant corresponding resource permissions, and users are assigned to different groups, thereby having different resource permissions.
 The group interface includes APIs for creating groups, deleting groups, modifying groups, and querying group-related information.
 
-> `GroupAPI` remains available at `/auth/groups`. That is the only group route on 1.7.0;
-> the `/graphspaces/DEFAULT/auth/groups` form used below was added by
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) and is available
-> alongside `/auth/groups` on current `master`.
+> `GroupAPI` remains at `/auth/groups`, the only group route on 1.7.0. The `/graphspaces/DEFAULT/auth/groups` route was
+> added by [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) and coexists with it on `master`.
 >
-> On the GraphSpace form the server generates the persisted group name:
-> `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 hex digits, so a group in
-> `DEFAULT` is addressed as `~hubble_role:v1:REVGQVVMVA:<32 hex>`, and its `id` is that
-> same value. The request's `group_name` is only a client label. Pass the id returned by
-> the create response to the requests below; the `-69:all` form is the 1.5.x one and
-> identifies no GraphSpace group.
+> The GraphSpace API generates each persisted group name as `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 hex digits.
+> For `DEFAULT`, the name and ID look like `~hubble_role:v1:REVGQVVMVA:<32 hex>`; request `group_name` is only a client
+> label. Use the ID from the create response below; `-69:all` is a 1.5.x format, not a GraphSpace group ID.
 
 #### 10.3.1 Create Group
 
@@ -688,12 +672,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 ### 10.5 Association of Roles (Belong) API
 
 The association between users and user groups allows a user to be associated with one or more user groups. User groups have permissions for related resources, and the permissions for different user groups can be understood as different roles. In other words, users are associated with roles.  
-The API for associating roles includes creating, deleting, modifying, and
-querying the association of roles for users.
+The API for associating roles includes creating, deleting, modifying, and querying the association of roles for users.
 
-> The group ID below repeats the example from 10.3. Use the ID from your own
-> create response. For later requests, copy the `id` returned by the
-> create-belong response and URL-encode `>` as `%3E` in the path.
+> Use your actual group ID from 10.3. For later requests, use the Belong response `id` and URL-encode `>` as `%3E` in URLs.
 
 #### 10.5.1 Create an Association of Roles for a User
 
@@ -871,13 +852,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 
 ### 10.6 Authorization (Access) API
 Grant permissions to user groups for resources, including operations such as READ, WRITE, DELETE, EXECUTE, etc.
-The authorization API includes: creating, deleting, modifying, and querying
-permissions.
+The authorization API includes: creating, deleting, modifying, and querying permissions.
 
-> The examples reuse the group ID from 10.3 and target ID from 10.4. Use the IDs
-> returned by your own create responses; the group ID is generated by the server.
-> For later requests, copy the access `id` from the create response and
-> URL-encode `>` as `%3E` in the path.
+> Use your actual group ID from 10.3 and target ID from 10.4. For later requests, use the Access response `id` and URL-encode `>` as `%3E` in URLs.
 
 #### 10.6.1 Create Authorization (Granting permissions to user groups for resources)
 

From d7592c5a06191df1f78d6b82a0fb7e862ff728c9 Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Sat, 26 Sep 2026 19:02:24 +0800
Subject: [PATCH 7/8] docs(auth): remove 1.5 compatibility notes

- Link release-specific behavior to the 1.7 site docs.

- Keep the current master versus 1.7 group routes clear.

- Remove outdated 1.5 path and ID descriptions.
---
 content/cn/docs/clients/restful-api/auth.md | 21 ++++++++-----------
 content/en/docs/clients/restful-api/auth.md | 23 +++++++++------------
 2 files changed, 19 insertions(+), 25 deletions(-)

diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 2316b2a418..78d7a988f8 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -5,15 +5,14 @@ weight: 16
 description: "Authentication（认证鉴权）REST 接口:管理用户、角色、权限和访问控制,实现细粒度的图数据安全机制。"
 ---
 
-> **版本变更说明**:
-> - 1.7.0+: 图空间范围的 Auth API 使用 GraphSpace 路径；资源 ID 与名称一致，GraphSpace 用户组 ID 由服务端生成。
-> - 1.5.x 及更早：图范围 Auth API 路径包含 graph 名称；部分用户组/资源 ID 使用旧格式，见 [1.5.x API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
+> **版本说明**：本文跟随当前 `master`；1.7 发布版行为见
+> [HugeGraph 1.7 REST API](/versions/1.7/cn/docs/clients/restful-api/auth/)。
 >
-> 1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`，1.5.x 使用 `/graphs/{graph}/auth/groups`。GraphSpace 用户组路由由
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 在 1.7.0 后加入，并与当前 `master` 的 `/auth/groups` 并存。
+> 1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`。当前 `master` 还通过
+> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 提供 `/graphspaces/{graphspace}/auth/groups`。
 >
-> 1.7.0 上 GraphSpace 路由未注册。`AuthenticationFilter` 标注了 `@PreMatching`，会在路由匹配前执行：缺少或无效凭据
-> 可能返回 401；IP 白名单拒绝可能返回 403。过滤器接受请求后，未匹配的路径返回 404；关闭鉴权时也可能返回 404。
+> 1.7.0 上 GraphSpace 用户组路由未注册。`AuthenticationFilter` 标注了 `@PreMatching`，会在路由匹配前执行：
+> 缺少或无效凭据可能返回 401，IP 白名单拒绝可能返回 403；过滤器接受请求后，未匹配的路径返回 404。关闭鉴权时也可能返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -33,8 +32,6 @@ city: Beijing})
 
 ##### 接口说明：
 用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。
-**注意**: 1.5.x 及更早版本中的用户组/资源 ID 使用 `-69:grant`、`-77:grant` 等旧格式；GraphSpace 用户组 ID 由服务端生成。
-
 ### 10.2 用户（User）API
 用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。
 
@@ -256,12 +253,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。  
 用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。  
 
-> `GroupAPI` 仍挂载在 `/auth/groups`，这是 1.7.0 上唯一的用户组路由。`/graphspaces/DEFAULT/auth/groups` 由
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 加入，当前 `master` 同时提供这两种路径。
+> `GroupAPI` 仍挂载在 `/auth/groups`，这是 1.7.0 上唯一的用户组路由。当前 `master` 还提供
+> `/graphspaces/DEFAULT/auth/groups`，该路由由 [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 加入。
 >
 > GraphSpace 用户组名由服务端按 `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 位十六进制生成。
 > `DEFAULT` 中的名称和 ID 形如 `~hubble_role:v1:REVGQVVMVA:<32 hex>`；`group_name` 仅是客户端标签。下文请使用
-> 创建响应中的 ID；`-69:all` 是 1.5.x 格式，不能标识 GraphSpace 用户组。
+> 创建响应中的 ID。
 
 #### 10.3.1 创建用户组
 
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index f8e84c1bb9..da4af99061 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -5,16 +5,15 @@ weight: 16
 description: "Authentication REST API: Manage users, roles, permissions, and access control to implement fine-grained graph data security."
 ---
 
-> **Version Change Notice**:
-> - 1.7.0+: GraphSpace-scoped Auth paths use `/graphspaces/{graphspace}/auth/...`; target IDs match names, while GraphSpace group IDs are server-generated.
-> - 1.5.x and earlier: Graph-scoped Auth paths include the graph name; see [1.5.x REST API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0).
+> **Version Change Notice**: This page tracks current `master`. For release behavior, see
+> [HugeGraph 1.7 REST API](/versions/1.7/docs/clients/restful-api/auth/).
 >
-> On 1.7.0, `GroupAPI` is `/auth/groups`; 1.5.x used `/graphs/{graph}/auth/groups`. The GraphSpace route was added by
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) after 1.7.0 and coexists with `/auth/groups` on `master`.
+> On 1.7.0, `GroupAPI` is served at `/auth/groups`. Current `master` also serves GraphSpace groups at
+> `/graphspaces/{graphspace}/auth/groups`, added by [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096).
 >
-> On 1.7.0 the GraphSpace route is unregistered. `AuthenticationFilter` is `@PreMatching`, so it runs before route matching:
-> missing or invalid credentials can return 401; an IP outside the white list can return 403. If the filter accepts the
-> request, the unmatched path returns 404. A 404 can also occur when authentication is disabled.
+> On 1.7.0, the GraphSpace group route is unregistered. `AuthenticationFilter` is `@PreMatching`, so it runs before route
+> matching: missing or invalid credentials can return 401; a non-whitelisted IP can return 403; an accepted request reaches
+> route matching and returns 404. A 404 can also occur when authentication is disabled.
 
 ### 10.1 User Authentication and Access Control
 
@@ -29,8 +28,6 @@ Description: User 'boss' has read permission for people in the 'graph1' graph fr
 
 ##### Interface Description:
 The core of user authentication and access control is 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI. Alongside them, ManagerAPI grants graphspace-level manager roles, LoginAPI issues and verifies tokens, and ProjectAPI groups several graphs so that permissions can be granted for the whole set at once.
-**Note** Legacy 1.5.x group/target IDs include `-69:grant` and `-77:grant`; GraphSpace group IDs are server-generated.
-
 ### 10.2 User (User) API
 The user interface includes APIs for creating users, deleting users, modifying users, and querying user-related information.
 
@@ -253,12 +250,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 Groups grant corresponding resource permissions, and users are assigned to different groups, thereby having different resource permissions.
 The group interface includes APIs for creating groups, deleting groups, modifying groups, and querying group-related information.
 
-> `GroupAPI` remains at `/auth/groups`, the only group route on 1.7.0. The `/graphspaces/DEFAULT/auth/groups` route was
-> added by [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) and coexists with it on `master`.
+> `GroupAPI` remains at `/auth/groups`, the only group route on 1.7.0. Current `master` also serves `/graphspaces/DEFAULT/auth/groups`,
+> added by [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096).
 >
 > The GraphSpace API generates each persisted group name as `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 hex digits.
 > For `DEFAULT`, the name and ID look like `~hubble_role:v1:REVGQVVMVA:<32 hex>`; request `group_name` is only a client
-> label. Use the ID from the create response below; `-69:all` is a 1.5.x format, not a GraphSpace group ID.
+> label. Use the ID returned by the create response below.
 
 #### 10.3.1 Create Group
 

From a2223b72a0b536cab574e888e49e26361f249862 Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Sat, 26 Sep 2026 20:03:43 +0800
Subject: [PATCH 8/8] docs(auth): clarify 1.7 routing notes

- Link release-specific behavior to the published 1.7 docs.

- Explain master and 1.7 group routes in plain Chinese.

- Replace unsupported internal links to fix source validation.
---
 content/cn/docs/clients/restful-api/auth.md | 25 ++++++++++-----------
 content/en/docs/clients/restful-api/auth.md |  2 +-
 2 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 78d7a988f8..bc8fe55919 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -5,14 +5,14 @@ weight: 16
 description: "Authentication（认证鉴权）REST 接口:管理用户、角色、权限和访问控制,实现细粒度的图数据安全机制。"
 ---
 
-> **版本说明**：本文跟随当前 `master`；1.7 发布版行为见
-> [HugeGraph 1.7 REST API](/versions/1.7/cn/docs/clients/restful-api/auth/)。
+> **版本说明**：本页介绍当前 `master` 的接口；1.7 发布版见
+> [1.7 版 REST API](https://hugegraph.apache.org/versions/1.7/cn/docs/clients/restful-api/auth/)。
 >
-> 1.7.0 的 `GroupAPI` 挂载于 `/auth/groups`。当前 `master` 还通过
-> [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 提供 `/graphspaces/{graphspace}/auth/groups`。
+> 1.7.0 中，用户组接口只有 `/auth/groups`。当前 `master` 还提供 GraphSpace 用户组接口
+> `/graphspaces/{graphspace}/auth/groups`，由 [PR #3096](https://github.com/apache/hugegraph/pull/3096) 加入。
 >
-> 1.7.0 上 GraphSpace 用户组路由未注册。`AuthenticationFilter` 标注了 `@PreMatching`，会在路由匹配前执行：
-> 缺少或无效凭据可能返回 401，IP 白名单拒绝可能返回 403；过滤器接受请求后，未匹配的路径返回 404。关闭鉴权时也可能返回 404。
+> 1.7.0 没有注册带 GraphSpace 前缀的用户组接口。`AuthenticationFilter` 会先检查白名单和凭据，再匹配路由：IP 不在白名单内返回 403，
+> 缺少或无效凭据返回 401。检查通过后，因路由不存在会返回 404；关闭鉴权且白名单检查通过时，也会返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -253,12 +253,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。  
 用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。  
 
-> `GroupAPI` 仍挂载在 `/auth/groups`，这是 1.7.0 上唯一的用户组路由。当前 `master` 还提供
-> `/graphspaces/DEFAULT/auth/groups`，该路由由 [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096) 加入。
+> 本节的 GraphSpace 用户组路径只在当前 `master` 中提供；1.7.0 的用户组接口只有 `/auth/groups`。该路径由
+> [PR #3096](https://github.com/apache/hugegraph/pull/3096) 加入。
 >
-> GraphSpace 用户组名由服务端按 `~hubble_role:v1:` + base64url(graphspace) + `:` + 32 位十六进制生成。
-> `DEFAULT` 中的名称和 ID 形如 `~hubble_role:v1:REVGQVVMVA:<32 hex>`；`group_name` 仅是客户端标签。下文请使用
-> 创建响应中的 ID。
+> GraphSpace 用户组名由服务端生成，格式为 `~hubble_role:v1:` + GraphSpace 名称的 base64url 编码 + `:` + 32 个十六进制字符。
+> 例如，`DEFAULT` 的名称和 ID 都是 `~hubble_role:v1:REVGQVVMVA:<32 hex>`。请求中的 `group_name` 只是客户端标签；后续请求请用创建响应返回的 ID。
 
 #### 10.3.1 创建用户组
 
@@ -674,7 +673,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/grant
 关联用户和用户组的关系，一个用户可以关联一个或者多个用户组。用户组拥有相关资源的权限，不同用户组的资源权限可以理解为不同的角色。即给用户关联角色。  
 关联角色接口包括：用户关联角色的创建、删除、修改和查询。
 
-> 用户组 ID 沿用 10.3 示例；实际调用时请使用自己的响应 ID。后续请求使用 Belong 响应中的 `id`，并将 URL 中的 `>` 编码为 `%3E`。
+> 下例沿用 10.3 的用户组 ID。实际调用时请换成自己创建响应中的 ID。后续操作使用 Belong 创建响应里的 `id`，并将 URL 路径中的 `>` 编码为 `%3E`。
 
 #### 10.5.1 创建用户的关联角色
 
@@ -853,7 +852,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
 给用户组赋予资源的权限，主要包含：读操作 (READ)、写操作 (WRITE)、删除操作 (DELETE)、执行操作 (EXECUTE) 等。  
 赋权接口包括：赋权的创建、删除、修改和查询。
 
-> 使用 10.3 返回的用户组 ID 和 10.4 返回的资源 ID；实际调用时请使用自己的响应值。后续请求使用 Access 响应中的 `id`，并将 URL 中的 `>` 编码为 `%3E`。
+> 下例使用 10.3 和 10.4 返回的用户组 ID、资源 ID。实际调用时请换成自己的响应值。后续操作使用 Access 创建响应里的 `id`，并将 URL 路径中的 `>` 编码为 `%3E`。
 
 #### 10.6.1 创建赋权 (用户组赋予资源的权限)
 
diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md
index da4af99061..f11693e945 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -6,7 +6,7 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc
 ---
 
 > **Version Change Notice**: This page tracks current `master`. For release behavior, see
-> [HugeGraph 1.7 REST API](/versions/1.7/docs/clients/restful-api/auth/).
+> [HugeGraph 1.7 REST API](https://hugegraph.apache.org/versions/1.7/docs/clients/restful-api/auth/).
 >
 > On 1.7.0, `GroupAPI` is served at `/auth/groups`. Current `master` also serves GraphSpace groups at
 > `/graphspaces/{graphspace}/auth/groups`, added by [apache/hugegraph#3096](https://github.com/apache/hugegraph/pull/3096).