1.0.0

鉴权认证

鉴权方式

石墨 API 授权通过 Access Token 作为接口调用的凭证，接口调用方在对 API 发起请求时，需在 HTTP Header 加入以下授权参数：

  Authorization: Bearer <Access Token>

一个 Access Token 对应一个文档，即页面刷新、关闭重新打开或打开其他文档均需要重新生成 Access Token。

授权流程


  +--------+      ID/Secret      +--------+
  |        | +-----------------> |        |
  |        |                     |        |
  |        |    Access Token     |        |
  | Client | <-----------------+ |  石墨  |
  |        |                     |        |
  |        |    Access Token     |        |
  |        | +-----------------> |        |
  +--------+                     +--------+

ID/Secret 为石墨提供的 ClientID、ClientSecret。

Access Token

Access Token 数据结构如下：

{
  "scope": "write",
  "tokenType": "bearer",
  "accessToken": "70615e7c1e08fc7805c0df0e4dbc595600814f70b2b916c0e737e6ca2f914e7d",
  "refreshToken": "70615e7c1e08fc7805c0df0e4dbc595600814f70b2b916c0e737e6ca2f914e7d",
  "expireTime": "2018-06-12T09:50:23.000Z"
}
  • Access Token 有效期默认为 24 小时，有效期内同一个用户可重复使用该 Access Token 访问同一个文档。

accessToken.scope

scope 指该 Access Token 所具备的访问权限，如是否允许写入数据，用于限制 Access Token 可访问范围，避免 Access Token 泄漏、错误调用 API 等情况。

目前可用值：

名称描述
public 只可访问公开数据。
read 只可访问公开和需验证用户权限的数据。包含 `public` 的权限。
write 可读取和写入数据。包含 `read` 和 `public` 的权限。
user 允许访问所有用户相关 API。包含所有 `user:` 开头的权限。
user:create 允许访问创建用户的 API。

和 accessToken.info 不同的是，scope 仅用于判断能否访问指定 API，SDK 服务器会先比较 scope 是否匹配，在比较 info 中的权限：

  • scope: 'read 能访问用户的信息 (如 GET /users/me) ，但不能执行更新用户信息或创建文件等操作；
  • scope: 'write' 和 info.filePermissions.editable: false 的 Access Token 能更新用户信息 PATCH /users/:user，但不能撰写文档，因此 POST /files/<GUID>/compose 将会返回 401 错误；
  • scope: 'read' 和 info.filePermissions.editable: true 的 Access Token 由于 scope 不具备写权限，因此 POST /files/<GUID>/compose 将会返回 401 错误；
  • scope: 'read' 和 info: null 因为没有 info 信息，该 Access Token 只能访问部分接口 POST /files/<GUID>/compose 将会返回 401 错误。

accessToken.info

由于 SDK 并不存储用户和文档的具体关系 (如权限) ，因此针对单个 Access Token，需要通过 info 来标记用户对指定文档的权限。

info 仅在 file 资源接口中生效，如获取文件接口 (GET /files/<GUID>) , 但创建文件接口 (POST /files) 不需要info`。

info 需以 JSON 字符串形式发送到 SDK 服务器 (如何发送请看获取 Access Token) ，数据格式如下：

{
  "fileGuid": "JyRX1679PL86rbTk",
  "filePermissions": {
    "editable": true,
    "commentable": true,
    "readable": true
  }
}

fileGuid：为对应的文件的 GUID。

filePermissions：为用户对该文件所拥有的权限：

名称类型说明
readableboolean对文档的读权限，如允许匿名用户访问文档，但不可编辑。
readable 为必填项，仅当 editable 为 true 时可忽略。
readonly 已标记为弃用，未来将会删除，请更改为 readable
editableboolean对文档的编辑权限
commentableboolean对文档的评论权限，目前需和 editable 一致

获取 Access Token

使用 Client Credentials 获取 Access Token

接口

POST <SHIMO_API>/oauth2/token/

参数说明

Content-Type: application/json

参数类型必填说明
clientIdStringY石墨提供的 ClientID
clientSecretStringY石墨提供的 ClientSecret
clientUserIdStringY请求授权的用户标识
grantTypeStringY授权模式，此处需用 client_credentials
scopeStringY授权范围，为 write、read 和 public 中一个
infoStringN访问指定文档时需要的授权信息，为序列化后的 JSON 字符串

什么是 clientUserId

clientUserId 意为所请求授权的用户的身份标识，可以用户 ID、用户名或用户邮箱等。

用于在用户和文档数据不储存在石墨数据库时，和石墨所存储的数据进行用户关联用。

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/oauth2/token', {
  method: 'POST',
  body: JSON.stringify({
    clientId: 'shimo',
    ClientSecret: 'shimo',
    grantType: 'client_credentials',
    clientUserId: '1',
    scope: 'write',
    info: JSON.stringify({
      fileGuid: 'JyRX1679PL86rbTk',
      filePermissions: {
        editable: true,
        writeable: true,
        readonly: true
      }
    })
  })
})
  .then(res => res.json())
  .then(body => console.log(body.data))

返回示例

{
  "scope": "write",
  "tokenType": "bearer",
  "accessToken": "70615e7c1e08fc7805c0df0e4dbc595600814f70b2b916c0e737e6ca2f914e7d",
  "refreshToken": "70615e7c1e08fc7805c0df0e4dbc595600814f70b2b916c0e737e6ca2f914e7d",
  "expireTime": "2018-06-12T09:50:23.000Z"
}

使用 Refresh Token 获取新的 Access Token

不是所有 client 都具备 Refresh Token 权限，如遇到问题，请联系客服。

接口

POST <SHIMO_API>/oauth2/token/

参数说明

Content-Type: application/json

参数类型必填说明
clientIdStringY石墨提供的 ClientID
clientSecretStringY石墨提供的 ClientSecret
grantTypeStringY授权模式，此处需用 refresh_token
clientUserIdNumberY请求授权的用户标识
refreshTokenStringN用于刷新授权码

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/oauth2/token', {
  method: 'POST',
  body: JSON.stringify({
    grantType: 'refresh_token',
    clientUserId: 'shimo',
    refreshToken: '70615e7c1e08fc7805c0df0e4dbc595600814f70b2b916c0e737e6ca2f914e7d'
  })
})
  .then(res => res.json())
  .then(body => console.log(body.data))

返回参数

参数类型说明
accessTokenString授权码
refreshTokenString用于刷新授权码
scopeStringAccess Token 授权的范围
expiresInStringAccess Token 的过期时间
tokenTypeStringAccess Token 类型，默认 bearer

吊销 Access Token

接口

POST <SHIMO_API>/oauth2/revoke/

参数说明

Content-Type: application/json

参数类型必填说明
accessTokenStringY需要吊销的 Access Token

代码示例

const request = require('node-fetch')

fetch('<SHIMO_API>/oauth2/revoke', {
  method: 'POST',
  body: JSON.stringify({
    accessToken: '70615e7c1e08fc7805c0df0e4dbc595600814f70b2b916c0e737e6ca2f914e7d'
  })
})
  .then(res => res.json())
  .then(body => console.log(body.data))

状态码说明

204 删除成功

← 协同编辑通用模块文档 →