API授权与个人访问令牌

授权说明

授权模式

使用凭证式（client credentials）授权模式。

授权模式流程说明

第一步，A 应用在命令行向 B 发出请求。 第二步，B 网站验证通过以后，直接返回令牌。

授权模式结构说明

接口说明

获取access_token

获取access_token。开发者需要缓存access_token，用于后续接口的调用。当access_token失效或过期时，需要重新获取。

请求URL

GET /api/oauth2/server/tokens?grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET} HTTP/1.1
Accept: application/json

URL 参数

字段	类型	是否必须	描述
grant_type	STRING	是	授权类型，固定值 ：client_credentials。表示采用凭证式
client_id	STRING	是	客户端id
client_secret	STRING	是	客户端secret

返回对象的格式说明

字段	类型	说明
access_token	STRING	access_token
token_type	STRING	固定值 "bearer"
expires_in	STRING	有效时间，单位为秒，默认为12小时
scope	STRING	授权作用域，目前只支持 "sudo"

校验access_token

校验access_token

请求URL

GET /api/oauth2/server/tokens/check?token=${ACCESS_TOKEN} HTTP/1.1

URL 参数

字段	类型	是否必须	描述
token	STRING	是	需较验的 access_token

返回对象的格式说明

字段	类型	说明
access_token	STRING	access_token
token_type	STRING	固定值 "bearer"
expires_in	STRING	有效时间，单位为秒
scope	STRING	授权作用域，目前只支持 "sudo"

撤销access_token

撤销access_token

请求URL

GET /api/oauth2/server/tokens/revoke?token=${ACCESS_TOKEN} HTTP/1.1

URL 参数

字段	类型	是否必须	描述
token	STRING	是	待撤销的 access_token

返回对象的格式说明

字段	类型	说明
code	INTEGER	0 为成功，其它值为失败
msg	STRING	操作结果

个人访问令牌（PAT）

使用说明

个人访问令牌（PAT）接口用于当前登录用户获取或创建专属的 API 调用凭证，并基于该凭证生成 access_token。

注意

以下接口都要求当前用户已经通过 Web 登录建立会话（例如浏览器携带 sid、csrf、_USER_SESSION_ID 等登录态 Cookie）。

获取当前用户的 PAT client

读取当前登录用户已经存在的 PAT client。

请求URL

GET /api/oauth2/server/personal-access-token HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

返回对象的格式说明

当用户尚未创建 PAT client 时，data 返回 null；存在时返回如下结构。

字段	类型	说明
name	STRING	当前用户 PAT client 的名称，默认格式为 hbi-personal-access-token-{userId}
clientId	STRING	当前用户 PAT client 的 client_id
clientSecret	STRING	当前用户 PAT client 的 client_secret

接口示例

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "msg": "success",
  "data": {
    "name": "hbi-personal-access-token-42",
    "clientId": "pat_client_alice_123",
    "clientSecret": "pat_secret_abc"
  }
}

创建或复用当前用户的 PAT client

为当前登录用户创建 PAT client；如果该用户已经存在 PAT client，则直接返回已有凭证。

请求URL

POST /api/oauth2/server/personal-access-token HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

返回对象的格式说明

字段	类型	说明
name	STRING	当前用户 PAT client 的名称，默认格式为 hbi-personal-access-token-{userId}
clientId	STRING	当前用户 PAT client 的 client_id
clientSecret	STRING	当前用户 PAT client 的 client_secret

接口示例

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "msg": "success",
  "data": {
    "name": "hbi-personal-access-token-42",
    "clientId": "pat_client_alice_123",
    "clientSecret": "pat_secret_abc"
  }
}

删除当前用户的 PAT client

删除当前登录用户的 PAT client，用于凭据泄露后的自助失效。删除后，依赖该 client 的 token 会在后续请求校验时失效；如果再次使用 device login 或 PAT token 生成接口，会重新创建/复用新的 PAT client。

请求URL

DELETE /api/oauth2/server/personal-access-token HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

返回对象的格式说明

字段	类型	说明
code	INTEGER	0 表示删除成功
msg	STRING	操作结果

生成个人 access_token

基于当前登录用户的 PAT client 生成新的 access_token。如果用户还没有 PAT client，会先按当前用户创建/复用对应 client，再返回 token payload。

请求URL

POST /api/oauth2/server/personal-access-token/token HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

返回对象的格式说明

字段	类型	说明
name	STRING	当前用户 PAT client 的名称，默认格式为 hbi-personal-access-token-{userId}
clientId	STRING	当前用户 PAT client 的 client_id
clientSecret	STRING	当前用户 PAT client 的 client_secret
accessToken	STRING	新生成的 access_token
tokenType	STRING	固定值 bearer
expiresIn	LONG	token 有效期，单位秒
scope	STRING	授权范围，当前固定为 api

接口示例

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "msg": "success",
  "data": {
    "name": "hbi-personal-access-token-42",
    "clientId": "pat_client_alice_123",
    "clientSecret": "pat_secret_abc",
    "accessToken": "fresh-token",
    "tokenType": "bearer",
    "expiresIn": 3600,
    "scope": "api"
  }
}

access_token及sudo说明

access_token

在Header中携带

GET /api/{URI} HTTP/1.1
Authorization：Bearer ${ACCESS_TOKEN}

拼接在url中作为Query String Parameter的一部分

GET /api/{URI}?access_token=${ACCESS_TOKEN} HTTP/1.1

sudo

设置sudo

sudo拼接在url中作为requestParam，sudo支持通过用户的id、loginName(登录名)、email（邮箱）、mobile（手机）传递用户身份。 以下四种sudo格式为：

1. sudo=uid:${UID}
2. sudo=loginName:${LOGIN_NAME}
3. sudo=email:${EMAIL}
4. sudo=mobile:${MOBILE}

注意

sudo=username:${LOGIN_NAME} (不推荐使用)

GET /api/{URI}?access_token=${ACCESS_TOKEN}&sudo=uid:${UID} HTTP/1.1

设置租户

如果想使用sudo 功能，操作租户的数据，则要传递 tenantId 或者 tenantCode

GET /api/{URI}?access_token=${ACCESS_TOKEN}&sudo=uid:${UID}&tenantId=${tenantId} HTTP/1.1

或

GET /api/{URI}?access_token=${ACCESS_TOKEN}&sudo=uid:${UID}&tenantCode=${tenantCode} HTTP/1.1