跳转到主要内容

Authentication API

Authentication（认证鉴权）REST 接口:管理用户、角色、权限和访问控制,实现细粒度的图数据安全机制。

版本说明：本页介绍当前 master 的接口。历史用法请切换到对应多版本页面： 1.7 版认证 API 或 1.5 版认证 API。

用户、图空间用户组、资源、关联和赋权接口使用 /graphspaces/{graphspace}/auth/...。登录、登出和 token 校验仍使用 /auth/login、/auth/logout、/auth/verify；图空间默认角色接口位于 /graphspaces/{graphspace}/role。源码保留顶层 /auth/groups，本页组接口示例使用图空间范围接口。

下文 {group_id}、{target_id}、{another_target_id}、{belong_id} 和 {access_id} 均为占位符，使用前须替换为对应响应中的 id。将 ID 放入 URL 路径时，还须按 URL 路径组件规则编码。

10.1 用户认证与权限控制

开启权限及相关配置请先参考 权限配置 文档

用户认证与权限控制概述：

HugeGraph 支持多用户认证、以及细粒度的权限访问控制，采用基于“用户 - 用户组 - 操作 - 资源”的 4 层设计，灵活控制用户角色与权限。 资源描述了图数据库中的数据，比如符合某一类条件的顶点，每一个资源包括 type、label、properties 三个要素，共有 18 种 type、 任意 label、任意 properties 的组合形成的资源，一个资源的内部条件是且关系，多个资源之间的条件是或关系。用户可以属于一个或多个用户组，每个用户组可以拥有对任意个资源的操作权限，操作类型包括：读、写、删除、执行等种类。HugeGraph 支持动态创建用户、用户组、资源， 支持动态分配或取消权限。初始化数据库时超级管理员用户被创建，后续可通过超级管理员创建各类角色用户，新创建的用户如果被分配足够权限后，可以由其创建或管理更多的用户。

举例说明：

user(name=boss) -belong-> group(name=all) -access(read)-> target(graph=graph1, resource={label: person, city: Beijing})
描述：用户’boss’拥有对’graph1’图中北京人的读权限。

接口说明：

用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。

10.2 用户（User）API

用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。

10.2.1 创建用户

Params
  • user_name: 用户名称
  • user_password: 用户密码
  • user_nickname: 用户昵称
  • user_phone: 用户手机号
  • user_email: 用户邮箱
  • user_avatar: 用户头像地址
  • user_description: 用户描述

其中 user_name 和 user_password 为必填，其余为选填。

Request Body
1{
2    "user_name": "boss",
3    "user_password": "******",
4    "user_phone": "182****9088",
5    "user_email": "123@xx.com"
6}
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/auth/users
Response Status
1201
Response Body

返回报文中，密码为加密后的密文

 1{
 2    "user_password": "******",
 3    "user_email": "123@xx.com",
 4    "user_update": "2020-11-17 14:31:07.833",
 5    "user_name": "boss",
 6    "user_creator": "admin",
 7    "user_phone": "182****9088",
 8    "id": "boss",
 9    "user_create": "2020-11-17 14:31:07.833"
10}

10.2.2 删除用户

Params
  • id: 需要删除的用户 Id
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/auth/users/test
Response Status
1204

10.2.3 修改用户

Params
  • id: 需要修改的用户 Id
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/users/test
Request Body

修改 user_password 和 user_phone。user_name 不可修改，传了也必须与已有名称一致。

1{
2    "user_name": "test",
3    "user_password": "******",
4    "user_phone": "183****9266"
5}
Response Status
1200
Response Body

返回结果是包含修改过的内容在内的整个用户对象

1{
2    "user_password": "******",
3    "user_update": "2020-11-12 10:29:30.455",
4    "user_name": "test",
5    "user_creator": "admin",
6    "user_phone": "183****9266",
7    "id": "test",
8    "user_create": "2020-11-12 10:27:13.601"
9}

10.2.4 查询用户列表

Params
  • name: 只返回该名称的用户，传该参数时返回的是单个用户对象而不是列表，用户不存在时返回 404
  • limit: 返回结果条数的上限，默认为 100
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/users
Response Status
1200
Response Body
 1{
 2    "users": [
 3        {
 4            "user_password": "******",
 5            "user_update": "2020-11-11 11:41:12.254",
 6            "user_name": "admin",
 7            "user_creator": "system",
 8          "id": "admin",
 9            "user_create": "2020-11-11 11:41:12.254"
10        }
11    ]
12}

10.2.5 查询某个用户

Params
  • id: 需要查询的用户 Id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/users/admin
Response Status
1200
Response Body
1{
2    "user_password": "******",
3    "user_update": "2020-11-11 11:41:12.254",
4    "user_name": "admin",
5    "user_creator": "system",
6    "id": "admin",
7    "user_create": "2020-11-11 11:41:12.254"
8}

10.2.6 查询某个用户的角色

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
Response Status
1200
Response Body
 1{
 2    "roles": {
 3        "hugegraph": {
 4            "READ": [
 5                {
 6                    "type": "ALL",
 7                    "label": "*",
 8                    "properties": null
 9                }
10            ]
11        }
12    }
13}

10.3 用户组（Group）API

用户组会赋予相应的资源权限，用户会被分配不同的用户组，即可拥有不同的资源权限。
用户组接口包括：创建用户组，删除用户组，修改用户组，和查询用户组相关信息接口。

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_description: 用户组描述
Request Body
1{
2    "group_name": "all",
3    "group_description": "group can do anything"
4}

group_name 为必填字段；图空间范围的用户组持久化名称由服务端生成，不能用此字段自定义。请从创建响应中复制 id，用于后续关联、授权、查询、更新或删除。

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
Response Status
1201
Response Body
1{
2    "group_creator": "admin",
3    "group_name": "<服务端生成的图空间范围名称>",
4    "group_create": "2020-11-11 15:46:08.791",
5    "group_update": "2020-11-11 15:46:08.791",
6    "id": "{group_id}",
7    "group_description": "group can do anything"
8}

10.3.2 删除用户组

Params
  • id: 需要删除的用户组 Id
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/{group_id}
Response Status
1204

10.3.3 修改用户组

Params
  • id: 需要修改的用户组 Id
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/{group_id}
Request Body

修改 group_description。GraphSpace 形式下这里的 group_name 应当省略，或等于服务端生成的名称，传入其他值会被拒绝并提示 “The name of group can’t be updated”。

1{
2    "group_description": "grant"
3}
Response Status
1200
Response Body

返回结果是包含修改过的内容在内的整个用户组对象

1{
2    "group_creator": "admin",
3    "group_name": "<服务端生成的图空间范围名称>",
4    "group_create": "2020-11-12 09:50:58.458",
5    "group_update": "2020-11-12 09:57:58.155",
6    "id": "{group_id}",
7    "group_description": "grant"
8}

10.3.4 查询用户组列表

Params
  • limit: 返回结果条数的上限
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
Response Status
1200
Response Body
 1{
 2    "groups": [
 3        {
 4            "group_creator": "admin",
 5            "group_name": "<服务端生成的图空间范围名称>",
 6            "group_create": "2020-11-11 15:46:08.791",
 7            "group_update": "2020-11-11 15:46:08.791",
 8            "id": "{group_id}",
 9            "group_description": "group can do anything"
10        }
11    ]
12}

10.3.5 查询某个用户组

Params
  • id: 需要查询的用户组 Id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/{group_id}
Response Status
1200
Response Body
1{
2    "group_creator": "admin",
3    "group_name": "<服务端生成的图空间范围名称>",
4    "group_create": "2020-11-11 15:46:08.791",
5    "group_update": "2020-11-11 15:46:08.791",
6    "id": "{group_id}",
7    "group_description": "group can do anything"
8}

10.4 资源（Target）API

资源描述了图数据库中的数据，比如符合某一类条件的顶点，每一个资源包括 type、label、properties 三个要素，共有 18 种 type、 任意 label、任意 properties 的组合形成的资源，一个资源的内部条件是且关系，多个资源之间的条件是或关系。
资源接口包括：资源的创建、删除、修改和查询。

10.4.1 创建资源

Params
  • target_name: 资源名称
  • target_graph: 资源图
  • target_url: 资源地址
  • target_resources: 资源定义 (列表)

target_resources 可以包括多个 target_resource，以列表的形式存储。
每个 target_resource 包含：

  • type：可选值 VERTEX, EDGE 等，可填 ALL，则表示可以是顶点或边；
  • label：可选值，⼀个顶点或边类型的名称，可填*，则表示任意类型；
  • properties：map 类型，可包含多个属性的键值对，必须匹配所有属性值，属性值⽀持填条件范围（age: P.gte(18)），properties 如果为 null 表示任意属性均可，如果属性名和属性值均为‘*ʼ也表示任意属性均可。

如精细资源：“target_resources”: [{“type”:“VERTEX”,“label”:“person”,“properties”:{“city”:“Beijing”,“age”:“P.gte(20)”}}]**
资源定义含义：类型是’person’的顶点，且城市属性是’Beijing’，年龄属性大于等于 20。

Request Body
 1{
 2    "target_name": "all",
 3    "target_graph": "hugegraph",
 4    "target_url": "127.0.0.1:8080",
 5    "target_resources": [
 6        {
 7            "type": "ALL"
 8        }
 9    ]
10}
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
Response Status
1201
Response Body
 1{
 2    "target_creator": "admin",
 3    "target_name": "all",
 4    "target_url": "127.0.0.1:8080",
 5    "target_graph": "hugegraph",
 6    "target_create": "2020-11-11 15:32:01.192",
 7    "target_resources": [
 8        {
 9            "type": "ALL",
10            "label": "*",
11            "properties": null
12        }
13    ],
14    "id": "{target_id}",
15    "target_update": "2020-11-11 15:32:01.192"
16}

10.4.2 删除资源

Params
  • id: 需要删除的资源 Id
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/{target_id}
Response Status
1204

10.4.3 修改资源

Params
  • id: 需要修改的资源 Id
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/{target_id}
Request Body

修改资源定义中的 type

1{
2    "target_resources": [
3        {
4            "type": "NONE"
5        }
6    ]
7}
Response Status
1200
Response Body

返回结果是包含修改过的内容在内的整个用户组对象

 1{
 2    "target_creator": "admin",
 3    "target_name": "all",
 4    "target_url": "127.0.0.1:8080",
 5    "target_graph": "hugegraph",
 6    "target_create": "2020-11-12 09:34:13.848",
 7    "target_resources": [
 8        {
 9            "type": "NONE",
10            "label": "*",
11            "properties": null
12        }
13    ],
14    "id": "{target_id}",
15    "target_update": "2020-11-12 09:37:12.780"
16}

10.4.4 查询资源列表

Params
  • limit: 返回结果条数的上限
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
Response Status
1200
Response Body
 1{
 2    "targets": [
 3        {
 4            "target_creator": "admin",
 5            "target_name": "all",
 6            "target_url": "127.0.0.1:8080",
 7            "target_graph": "hugegraph",
 8            "target_create": "2020-11-11 15:32:01.192",
 9            "target_resources": [
10                {
11                    "type": "ALL",
12                    "label": "*",
13                    "properties": null
14                }
15            ],
16            "id": "{target_id}",
17            "target_update": "2020-11-11 15:32:01.192"
18        },
19        {
20            "target_creator": "admin",
21            "target_name": "grant",
22            "target_url": "127.0.0.1:8080",
23            "target_graph": "hugegraph",
24            "target_create": "2020-11-11 15:43:24.841",
25            "target_resources": [
26                {
27                    "type": "GRANT",
28                    "label": "*",
29                    "properties": null
30                }
31            ],
32            "id": "{another_target_id}",
33            "target_update": "2020-11-11 15:43:24.841"
34        }
35    ]
36}

10.4.5 查询某个资源

Params
  • id: 需要查询的资源 Id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/{target_id}
Response Status
1200
Response Body
 1{
 2    "target_creator": "admin",
 3    "target_name": "all",
 4    "target_url": "127.0.0.1:8080",
 5    "target_graph": "hugegraph",
 6    "target_create": "2020-11-11 15:32:01.192",
 7    "target_resources": [
 8        {
 9            "type": "ALL",
10            "label": "*",
11            "properties": null
12        }
13    ],
14    "id": "{target_id}",
15    "target_update": "2020-11-11 15:32:01.192"
16}

10.5 关联角色（Belong）API

关联用户和用户组的关系，一个用户可以关联一个或者多个用户组。用户组拥有相关资源的权限，不同用户组的资源权限可以理解为不同的角色。即给用户关联角色。
关联角色接口包括：用户关联角色的创建、删除、修改和查询。

下例沿用 10.3 的用户组 ID。实际调用时请换成自己创建响应中的 ID。后续操作使用 Belong 创建响应里的 id，并将 URL 路径中的 > 编码为 %3E。

10.5.1 创建用户的关联角色

Params
  • user: 用户 Id
  • group: 用户组 Id
  • belong_description: 描述
Request Body
1{
2  "user": "boss",
3    "group": "{group_id}"
4}
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
Response Status
1201
Response Body
1{
2    "belong_create": "2020-11-11 16:19:35.422",
3    "belong_creator": "admin",
4    "belong_update": "2020-11-11 16:19:35.422",
5  "id": "{belong_id}",
6  "user": "boss",
7    "group": "{group_id}"
8}

10.5.2 删除关联角色

Params
  • id: 需要删除的关联角色 Id
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
Response Status
1204

10.5.3 修改关联角色

关联角色只能修改描述，不能修改 user 和 group 属性，如果需要修改关联角色，需要删除原来关联关系，新增关联角色。

Params
  • id: 需要修改的关联角色 Id
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
Request Body

修改 belong_description

1{
2    "belong_description": "update test"
3}
Response Status
1200
Response Body

返回结果是包含修改过的内容在内的整个用户组对象

1{
2    "belong_description": "update test",
3    "belong_create": "2020-11-12 10:40:21.720",
4    "belong_creator": "admin",
5    "belong_update": "2020-11-12 10:42:47.265",
6  "id": "{belong_id}",
7  "user": "boss",
8    "group": "{group_id}"
9}

10.5.4 查询关联角色列表

Params
  • user: 只返回该用户的关联关系
  • group: 只返回该角色的关联关系
  • limit: 返回结果条数的上限，默认为 100

user 和 group 不能同时使用。

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
Response Status
1200
Response Body
 1{
 2    "belongs": [
 3        {
 4            "belong_create": "2020-11-11 16:19:35.422",
 5            "belong_creator": "admin",
 6            "belong_update": "2020-11-11 16:19:35.422",
 7          "id": "{belong_id}",
 8          "user": "boss",
 9            "group": "{group_id}"
10        }
11    ]
12}

10.5.5 查看某个关联角色

Params
  • id: 需要查询的关联角色 Id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
Response Status
1200
Response Body
1{
2    "belong_create": "2020-11-11 16:19:35.422",
3    "belong_creator": "admin",
4    "belong_update": "2020-11-11 16:19:35.422",
5  "id": "{belong_id}",
6  "user": "boss",
7    "group": "{group_id}"
8}

10.6 赋权（Access）API

给用户组赋予资源的权限，主要包含：读操作 (READ)、写操作 (WRITE)、删除操作 (DELETE)、执行操作 (EXECUTE) 等。
赋权接口包括：赋权的创建、删除、修改和查询。

下例使用 10.3 和 10.4 返回的用户组 ID、资源 ID。实际调用时请换成自己的响应值。后续操作使用 Access 创建响应里的 id，并将 URL 路径中的 > 编码为 %3E。

10.6.1 创建赋权 (用户组赋予资源的权限)

Params
  • group: 用户组 Id
  • target: 资源 Id
  • access_permission: 权限许可
  • access_description: 赋权描述

access_permission：

  • READ：读操作，所有的查询，包括查询 Schema、查顶点/边，查询顶点和边的数量 VERTEX_AGGR/EDGE_AGGR，也包括读图的状态 STATUS、变量 VAR、任务 TASK 等；
  • WRITE：写操作，所有的创建、更新操作，包括给 Schema 增加 property key，给顶点增加或更新属性等；
  • DELETE：删除操作，包括删除元数据、删除顶点/边；
  • EXECUTE：执⾏操作，包括执⾏ Gremlin 语句、执⾏ Task、执⾏ metadata 函数；
Request Body
1{
2    "group": "{group_id}",
3    "target": "{target_id}",
4    "access_permission": "READ"
5}
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
Response Status
1201
Response Body
1{
2    "access_permission": "READ",
3    "access_create": "2020-11-11 15:54:54.008",
4    "id": "{access_id}",
5    "access_update": "2020-11-11 15:54:54.008",
6    "access_creator": "admin",
7    "group": "{group_id}",
8    "target": "{target_id}"
9}

10.6.2 删除赋权

Params
  • id: 需要删除的赋权 Id
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
Response Status
1204

10.6.3 修改赋权

赋权只能修改描述，不能修改用户组、资源和权限许可，如果需要修改赋权的关系，可以删除原来的赋权关系，新增赋权。

Params
  • id: 需要修改的赋权 Id
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
Request Body

修改 access_description

1{
2    "access_description": "test"
3}
Response Status
1200
Response Body

返回结果是包含修改过的内容在内的整个用户组对象

 1{
 2    "access_description": "test",
 3    "access_permission": "READ",
 4    "access_create": "2020-11-12 10:12:03.074",
 5    "id": "{access_id}",
 6    "access_update": "2020-11-12 10:16:18.637",
 7    "access_creator": "admin",
 8    "group": "{group_id}",
 9    "target": "{target_id}"
10}

10.6.4 查询赋权列表

Params
  • group: 只返回该角色的赋权记录
  • target: 只返回该资源上的赋权记录
  • limit: 返回结果条数的上限，默认为 100

group 和 target 不能同时使用。

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
Response Status
1200
Response Body
 1{
 2    "accesses": [
 3        {
 4            "access_permission": "READ",
 5            "access_create": "2020-11-11 15:54:54.008",
 6            "id": "{access_id}",
 7            "access_update": "2020-11-11 15:54:54.008",
 8            "access_creator": "admin",
 9            "group": "{group_id}",
10            "target": "{target_id}"
11        }
12    ]
13}

10.6.5 查询某个赋权

Params
  • id: 需要查询的赋权 Id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
Response Status
1200
Response Body
1{
2    "access_permission": "READ",
3    "access_create": "2020-11-11 15:54:54.008",
4    "id": "{access_id}",
5    "access_update": "2020-11-11 15:54:54.008",
6    "access_creator": "admin",
7    "group": "{group_id}",
8    "target": "{target_id}"
9}

10.7 图空间管理员（Manager）API

重要提示：在使用以下 API 之前，需要先创建图空间（graphspace）。请参考 Graphspace API 创建名为 gs1 的图空间。文档中的示例均假设已存在名为 gs1 的图空间

重要提示：管理员相关接口只在 PD 模式下可用，单机模式下会返回 400 和 GraphSpace management is not supported in standalone mode 错误信息。

  1. 图空间管理员 API 用于在 graphspace 维度给用户授予/回收管理员角色，并查询当前用户或其他用户在该 graphspace 下的角色信息。角色类型可取 SPACE、SPACE_MEMBER、ADMIN 。

10.7.1 检查当前登录用户是否拥有某个角色

Params
  • type: 需要校验的角色类型，必填，取值为 SPACE、SPACE_MEMBER、ADMIN 之一
Method & Url
1GET http://localhost:8080/graphspaces/gs1/auth/managers/check?type=SPACE_MEMBER
Response Status
1200
Response Body
1{
2  "check": true
3}

10.7.2 查询图空间管理员列表

Params
  • type: 角色类型，必填，取值为 SPACE、SPACE_MEMBER、ADMIN 之一。SPACE 返回图空间管理员，SPACE_MEMBER 返回图空间成员，ADMIN 返回整个集群的管理员
Method & Url
1GET http://localhost:8080/graphspaces/gs1/auth/managers?type=SPACE
Response Status
1200
Response Body
1{
2  "admins": [
3    "admin"
4  ]
5}

10.7.3 授权/创建图空间管理员

  • 下面在 gs1 下，将用户 boss 授权为 SPACE_MEMBER 角色
Params
  • user: 用户或角色名称，必填
  • type: 角色类型，必填，取值为 SPACE、SPACE_MEMBER、ADMIN 之一

把已经是图空间成员的用户授权为 SPACE 时会先回收其成员角色，反之同理。只有管理员可以授予 ADMIN。

Request Body
1{
2  "user": "boss",
3  "type": "SPACE_MEMBER"
4}
Method & Url
1POST http://localhost:8080/graphspaces/gs1/auth/managers
Response Status
1201
Response Body
1{
2  "user": "boss",
3  "type": "SPACE_MEMBER",
4  "graphspace": "gs1"
5}

10.7.4 取消图空间管理员权限

  • 下面在 gs1 下，将用户 boss 的 SPACE_MEMBER 角色删除
Params
  • user: 需要删除的用户名称，内置的 admin 用户不能从 ADMIN 中移除
  • type: 需要删除的角色类型，取值为 SPACE、SPACE_MEMBER、ADMIN 之一
Method & Url
1DELETE http://localhost:8080/graphspaces/gs1/auth/managers?user=boss&type=SPACE_MEMBER
Response Status
1204

10.7.5 查询指定用户在图空间中的角色

Params
  • user: 用户名称
Method & Url
1GET http://localhost:8080/graphspaces/gs1/auth/managers/role?user=boss
Response Status
1200
Response Body

返回的角色取自 ADMIN、SPACE、SPACE_MEMBER；用户在该图空间下不具备其中任何角色时返回 NONE。

1{
2  "user": "boss",
3  "graphspace": "gs1",
4  "roles": [
5    "SPACE_MEMBER"
6  ]
7}

10.7.6 检查当前登录用户是否拥有某个默认角色

默认角色是图空间的内置角色，参见 Graphspace API。role 的合法取值为 space、space_member、analyst 和 observer；graph 只在 role=observer 时生效。

Params
  • role: 默认角色名称，必填
  • graph: 图名称，选填，只在 role=observer 时使用
Method & Url
1GET http://localhost:8080/graphspaces/gs1/auth/managers/default?role=analyst
Response Status
1200
Response Body
1{
2  "check": true
3}

10.8 登录（Login）API

除了 HTTP Basic 认证之外，服务还可以签发 JWT token，之后通过 Authorization: Bearer <token> 请求头携带。登录相关接口不带图空间前缀。

token 使用 auth.token_secret 配置项签名，有效期为 auth.token_expire 秒（默认 86400）。该密钥的默认值在启动时随机生成，因此当 token 需要在重启后继续有效、或者需要被多个服务节点接受时，必须显式配置该项。

10.8.1 登录并获取 token

Params
  • user_name: 用户名称，必填
  • user_password: 用户密码，必填
  • token_expire: token 有效期（秒），选填
Request Body
1{
2    "user_name": "test",
3    "user_password": "******"
4}
Method & Url
1POST http://localhost:8080/auth/login
Response Status
1200

用户名或密码错误时返回 401。

Response Body
1{
2    "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX25hbWUiOiJ0ZXN0IiwidXNlcl9pZCI6InRlc3QiLCJleHAiOjE3MTIxMjM0NTZ9.PBs0iBt0PtqvLDpJvKrPHkyIzT1TICz9zJmMy8FvXVo"
3}

10.8.2 登出并使 token 失效

需要失效的 token 从请求头中获取，无需请求体。

Params

请求头说明：

  • Authorization: Bearer <token>，必填。只接受 Bearer 方式，其他方式返回 400。
Method & Url
1DELETE http://localhost:8080/auth/logout
Response Status
1204

token 非法或已过期时返回 401。

10.8.3 校验 token

Params

请求头说明：

  • Authorization: Bearer <token>，必填
Method & Url
1GET http://localhost:8080/auth/verify
Response Status
1200

token 非法或已过期时返回 401。

Response Body
1{
2    "user_name": "test",
3    "user_id": "test"
4}

10.9 项目（Project）API

项目把一组图和一个管理员角色、一个操作员角色绑定在一起，从而可以一次性对这组图授权。创建项目时会同时生成它的 project_target、project_admin_group 和 project_op_group，这些字段会在响应中返回，但不能由客户端设置。

10.9.1 创建项目

Params
  • project_name: 项目名称，必填
  • project_description: 项目描述，选填

创建时不能传 project_graphs，请使用下面的 add_graph 操作。

Request Body
1{
2    "project_name": "test_project",
3    "project_description": "this is a good project"
4}
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/auth/projects
Response Status
1201
Response Body
 1{
 2    "project_name": "test_project",
 3    "project_description": "this is a good project",
 4    "project_target": "project_test_project",
 5    "project_admin_group": "project_test_project_admin",
 6    "project_op_group": "project_test_project_op",
 7    "project_create": "2024-01-10 09:30:00.000",
 8    "project_update": "2024-01-10 09:30:00.000",
 9    "project_creator": "admin",
10    "id": "test_project"
11}

10.9.2 向项目中添加或移除图

Params
  • id: 项目 Id
  • action: add_graph 表示添加，remove_graph 表示移除
Request Body
1{
2    "project_graphs": [
3        "hugegraph"
4    ]
5}
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project?action=add_graph
Response Status
1200
Response Body

返回整个项目对象，其中包含更新后的图列表。

10.9.3 修改项目描述

Params
  • id: 项目 Id

不传 action 时表示修改描述，此时请求体中不能带 project_graphs。

Request Body
1{
2    "project_description": "update desc"
3}
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project
Response Status
1200

10.9.4 查询项目列表

Params
  • limit: 返回结果条数的上限，默认为 100
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/projects
Response Status
1200
Response Body
 1{
 2    "projects": [
 3        {
 4            "project_name": "test_project",
 5            "project_description": "this is a good project",
 6            "project_target": "project_test_project",
 7            "project_admin_group": "project_test_project_admin",
 8            "project_op_group": "project_test_project_op",
 9            "project_create": "2024-01-10 09:30:00.000",
10            "project_update": "2024-01-10 09:30:00.000",
11            "project_creator": "admin",
12            "id": "test_project"
13        }
14    ]
15}

10.9.5 查询某个项目

Params
  • id: 项目 Id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project
Response Status
1200

10.9.6 删除项目

Params
  • id: 项目 Id

删除前需要先把项目中的图全部移除。

Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/auth/projects/test_project
Response Status
1204
最后修改 2026-10-12 · feat: upgrade OINK to 1.2.0 and improve docs UX (#514) (6181c8705)