diff --git a/AGENTS.md b/AGENTS.md
index 6e89817082..7d310e85fa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +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.
+- 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 488ba51a46..bc8fe55919 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -5,9 +5,14 @@ weight: 16
 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)
+> **版本说明**：本页介绍当前 `master` 的接口；1.7 发布版见
+> [1.7 版 REST API](https://hugegraph.apache.org/versions/1.7/cn/docs/clients/restful-api/auth/)。
+>
+> 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` 会先检查白名单和凭据，再匹配路由：IP 不在白名单内返回 403，
+> 缺少或无效凭据返回 401。检查通过后，因路由不存在会返回 404；关闭鉴权且白名单检查通过时，也会返回 404。
 
 ### 10.1 用户认证与权限控制
 
@@ -27,8 +32,6 @@ 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)
-
 ### 10.2 用户（User）API
 用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。
 
@@ -248,13 +251,19 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
 
 ### 10.3 用户组（Group）API
 用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。  
-用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。
+用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。  
+
+> 本节的 GraphSpace 用户组路径只在当前 `master` 中提供；1.7.0 的用户组接口只有 `/auth/groups`。该路径由
+> [PR #3096](https://github.com/apache/hugegraph/pull/3096) 加入。
+>
+> GraphSpace 用户组名由服务端生成，格式为 `~hubble_role:v1:` + GraphSpace 名称的 base64url 编码 + `:` + 32 个十六进制字符。
+> 例如，`DEFAULT` 的名称和 ID 都是 `~hubble_role:v1:REVGQVVMVA:<32 hex>`。请求中的 `group_name` 只是客户端标签；后续请求请用创建响应返回的 ID。
 
 #### 10.3.1 创建用户组
 
 ##### Params
 
-- group_name: 用户组名称
+- group_name: 仅作为客户端标签 —— GraphSpace 形式下持久化的名称由服务端生成
 - group_description: 用户组描述
 
 ##### Request Body
@@ -284,10 +293,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"
 }
 ```
@@ -302,7 +311,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
@@ -320,14 +329,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"
 }
 ```
@@ -343,10 +352,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"
 }
 ```
@@ -376,10 +385,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"
         }
     ]
@@ -395,7 +404,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
@@ -409,10 +418,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"
 }
 ```
@@ -483,7 +492,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"
 }
 ```
@@ -498,7 +507,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
@@ -517,7 +526,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
@@ -557,7 +566,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"
 }
 ```
@@ -598,7 +607,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"
         },
         {
@@ -614,7 +623,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"
         }
     ]
@@ -630,7 +639,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
@@ -655,7 +664,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"
 }
 ```
@@ -664,6 +673,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
 关联用户和用户组的关系，一个用户可以关联一个或者多个用户组。用户组拥有相关资源的权限，不同用户组的资源权限可以理解为不同的角色。即给用户关联角色。  
 关联角色接口包括：用户关联角色的创建、删除、修改和查询。
 
+> 下例沿用 10.3 的用户组 ID。实际调用时请换成自己创建响应中的 ID。后续操作使用 Belong 创建响应里的 `id`，并将 URL 路径中的 `>` 编码为 `%3E`。
+
 #### 10.5.1 创建用户的关联角色
 
 ##### Params
@@ -677,7 +688,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
 ```json
 {
   "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -701,9 +712,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"
 }
 ```
 
@@ -716,7 +727,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/{belong_id}
 ```
 
 ##### Response Status
@@ -735,7 +746,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/{belong_id}
 ```
 
 ##### Request Body
@@ -760,9 +771,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"
 }
 ```
 
@@ -798,9 +809,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"
         }
     ]
 }
@@ -815,7 +826,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/{belong_id}
 ```
 
 ##### Response Status
@@ -831,9 +842,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"
 }
 ```
 
@@ -841,6 +852,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
 给用户组赋予资源的权限，主要包含：读操作 (READ)、写操作 (WRITE)、删除操作 (DELETE)、执行操作 (EXECUTE) 等。  
 赋权接口包括：赋权的创建、删除、修改和查询。
 
+> 下例使用 10.3 和 10.4 返回的用户组 ID、资源 ID。实际调用时请换成自己的响应值。后续操作使用 Access 创建响应里的 `id`，并将 URL 路径中的 `>` 编码为 `%3E`。
+
 #### 10.6.1 创建赋权 (用户组赋予资源的权限)
 
 ##### Params
@@ -860,8 +873,8 @@ access_permission：
 
 ```json
 {
-    "group": "-69:all",
-    "target": "-77:all",
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all",
     "access_permission": "READ"
 }
 ```
@@ -884,11 +897,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"
 }
 ```
 
@@ -902,7 +915,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/{access_id}
 ```
 
 ##### Response Status
@@ -921,7 +934,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/{access_id}
 ```
 
 ##### Request Body
@@ -943,13 +956,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"
 }
 ```
 
@@ -983,11 +996,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"
         }
     ]
 }
@@ -1002,7 +1015,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/{access_id}
 ```
 
 ##### Response Status
@@ -1017,11 +1030,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 7c37de996a..f11693e945 100644
--- a/content/en/docs/clients/restful-api/auth.md
+++ b/content/en/docs/clients/restful-api/auth.md
@@ -5,9 +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+: 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)
+> **Version Change Notice**: This page tracks current `master`. For release behavior, see
+> [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).
+>
+> 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
 
@@ -22,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** 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)
-
 ### 10.2 User (User) API
 The user interface includes APIs for creating users, deleting users, modifying users, and querying user-related information.
 
@@ -246,11 +250,18 @@ 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. 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 returned by the create response below.
+
 #### 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
@@ -280,10 +291,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"
 }
 ```
@@ -298,7 +309,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
@@ -316,14 +327,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"
 }
 ```
@@ -340,10 +352,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"
 }
 ```
@@ -373,10 +385,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"
         }
     ]
@@ -392,7 +404,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
@@ -406,10 +418,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"
 }
 ```
@@ -478,7 +490,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"
 }
 ```
@@ -492,7 +504,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
@@ -510,7 +522,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
@@ -551,7 +563,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"
 }
 ```
@@ -592,7 +604,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"
         },
         {
@@ -608,7 +620,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"
         }
     ]
@@ -624,7 +636,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
@@ -649,7 +661,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"
 }
 ```
@@ -659,6 +671,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.
 
+> 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
 
 ##### Params
@@ -672,7 +686,7 @@ The API for associating roles includes creating, deleting, modifying, and queryi
 ```json
 {
     "user": "boss",
-    "group": "-69:all"
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94"
 }
 ```
 
@@ -696,9 +710,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"
 }
 ```
 
@@ -711,7 +725,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/{belong_id}
 ```
 
 ##### Response Status
@@ -731,7 +745,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/{belong_id}
 ```
 
 ##### Request Body
@@ -756,9 +770,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"
 }
 ```
 
@@ -794,9 +808,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"
         }
     ]
 }
@@ -811,7 +825,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/{belong_id}
 ```
 
 ##### Response Status
@@ -827,9 +841,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"
 }
 ```
 
@@ -837,6 +851,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.
 
+> 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)
 
 ##### Params
@@ -856,8 +872,8 @@ Access permissions:
 
 ```json
 {
-    "group": "-69:all",
-    "target": "-77:all",
+    "group": "~hubble_role:v1:REVGQVVMVA:3a5d8f1c94b74e0fa6c2d18e5b0f7c94",
+    "target": "all",
     "access_permission": "READ"
 }
 ```
@@ -880,11 +896,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"
 }
 ```
 
@@ -897,7 +913,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/{access_id}
 ```
 
 ##### Response Status
@@ -917,7 +933,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/{access_id}
 ```
 
 ##### Request Body
@@ -943,13 +959,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"
 }
 ```
 
@@ -983,11 +999,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"
     }
   ]
 }
@@ -1002,7 +1018,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/{access_id}
 ```
 
 ##### Response Status
@@ -1017,11 +1033,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"
 }
 ```