Web 授权

网页应用登录授权是基于标准的 OAuth 2.0 协议实现的，通过金山文档帐号授权登录第三方网页应用的能力。

准备工作

在使用网页应用登录授权能力之前，你需要先仔细阅读服务商指南，根据文档中的指示在开发者后台创建一个应用，并获得应用的 app_id 和 app_key 。

注意

在开发者后台申请应用时，请注意 回调地址 的正确填写，此处的授权流程依赖该地址进行授权码的传递。

第一步：获取授权码

授权页链接

[GET] https://developer.kdocs.cn/h5/auth?app_id={app_id}&scope={scope}&redirect_uri={redirect_uri}&state={state }

链接参数说明

名称	类型	是否必填	说明
app_id	string	是	应用的 APPID，查看应用信息
scope	string	是	需申请的权限，用 `,` 分割， scope 权限说明
redirect_uri	string	是	应用注册的回调地址之一，采用 `encodeURIComponent()` 处理
state	string	否	由用户自定义，授权成功后会通过重定向带回
header	string	否	是否显示页面 header，默认 false 不显示

授权页

请按照上述说明填充链接参数，然后打开链接，进入开放平台授权页面。

用户点击授权后，会携带 code 和 state 自动跳转至所传递的 redirect_uri 。

授权页

提示

如果回调地址中含 ? 分隔符，code 参数会采用 & 拼接

location.href = `${redirect_uri}?code=${code}&state=${state}`

注意

code 的有效时间为 5 分钟，过期后返回错误码 20001 表示授权码无效，开发者需要重新发起授权流程。

第二步：获取令牌

提示

由于应用 appkey 和获取到的 access_token 安全级别比较高，后续刷新 access_token 、通过 access_token 获取用户信息等步骤，必须从服务器调用接口。

接口信息

请求方法： GET

请求路径： /api/v1/oauth2/access_token

请求主机： developer.kdocs.cn

签名方式：无

名称	是否必填	说明
Content-Type	是	固定为: `application/json`

Query 参数

名称	类型	是否必填	说明
code	string	是	用户授权返回 code
app_id	string	是	应用 APPID
app_key	string	是	应用 APPKEY

请求地址示例

[GET] https://developer.kdocs.cn/api/v1/oauth2/access_token?code={code}&app_id={APPID}&app_key={APPKEY}

返回参数

名称	类型	说明
code	int	非 0 表示失败，参考错误码说明
+ data	access_token {}	令牌内容
app_id	string	令牌所属的应用 id
access_token	string	令牌
expires_in	integer	令牌有效期，单位为 `秒`
refresh_token	string	刷新令牌，在授权未过期之前，可用于刷新/重新获取访问令牌

返回示例

{
  "code": 0,
  "data": {
    "app_id": "SX20220706XGEQGL",
    "access_token":




    
 "XiDvqrCkvBtAAooijpoMyHQiyeXUhPjk",
    "expires_in": 86400,
    "refresh_token": "oWtTFhASVZhwKpwOaxNtoRTourVnPxCC"
  "result": "ok"

第三步：刷新过期的令牌

由于 access_token 的有效期较短，当 access_token 过期后，可以使用 refresh_token 进行刷新， refresh_token 有效期为 90 天，当 refresh_token 失效之后，需要用户重新进行授权。

使用 refresh_token 刷新 access_token 时，会返回一个新的 access_token ，原 access_token 自动失效。

接口信息

请求方法： POST

请求路径： /api/v1/oauth2/refresh_token

请求主机： developer.kdocs.cn

签名方式：无

名称	是否必填	说明
Content-Type	是	固定为: `application/json`

Query 参数

名称	类型	是否必填	说明
app_id	string	是	应用唯一标识

Body 参数

名称	类型	是否必填	说明
app_key	string	是	应用密钥
refresh_token	string	是	填写通过 `code` 获取到的 `refresh_token` 参数

请求地址示例

[POST]  https://developer.kdocs.cn/api/v1/oauth2/refresh_token?app_id={app_id}
    "app_key": "{app_key}",
    "refresh_token": "{refresh_token}"

返回参数

名称	类型	说明
code	int	非 0 表示失败，参考错误码说明
+ data	refresh_token {}	新的令牌内容
app_id	string	令牌所属的应用 id
access_token	string	令牌
expires_in	integer	令牌有效期，单位为 `秒`
refresh_token	string	刷新令牌，在授权未过期之前，可用于刷新/重新获取访问令牌

返回示例

{
  "code": 0,
  "data": {
    "access_token": "XiDvqrCkvBtAAooijpoMyHQiyeXUhPjk",
    "app_id": "SX20220706XGEQGL",
    "expires_in": 7776000,
    "refresh_token": "oWtTFhASVZhwKpwOaxNtoRTourVnPxCC"
  "result": "ok"

Web 授权

准备工作

第一步：获取授权码

授权页链接

链接参数说明

授权页

第二步：获取令牌

接口信息

Header 参数

Query 参数

请求地址示例

返回参数

返回示例

第三步：刷新过期的令牌

接口信息

Header 参数

Query 参数

Body 参数

请求地址示例

返回参数

返回示例

Web 授权 #

准备工作 #

第一步：获取授权码 #

授权页链接 #

链接参数说明 #

授权页 #

第二步：获取令牌 #

接口信息 #

Header 参数 #

Query 参数 #

请求地址示例 #

返回参数 #

返回示例 #

第三步：刷新过期的令牌 #

接口信息 #

Header 参数 #

Query 参数 #

Body 参数 #

请求地址示例 #

返回参数 #

返回示例 #

Web 授权

准备工作

第一步：获取授权码

授权页链接

链接参数说明

授权页

第二步：获取令牌

接口信息

Header 参数

Query 参数

请求地址示例

返回参数

返回示例

第三步：刷新过期的令牌

接口信息

Header 参数

Query 参数

Body 参数

请求地址示例

返回参数

返回示例