调用服务端 API 生成 Token

本文介绍如何调用服务端 API 生成互动白板 Token。

功能介绍Copy Anchor Link

互动白板 Token 是互动白板服务对用户采用的一种鉴权方式。

你可以调用互动白板服务端 API 生成以下 Token：

• SDK Token：与特定的互动白板项目绑定，是级别最高的 Token。持有 SDK Token 的用户可操作该 Token 所绑定项目下的所有房间和文档转换任务。
• Room Token：与特定互动白板项目下的特定房间绑定。持有 Room Token 的用户可操作绑定的房间。
• Task Token：与特定项目下的特定文档转换任务绑定。持有 Task Token 的用户可操作绑定的文档转换任务。

调用互动白板服务端 API 生成每种 Token 时，你可以设置 Token 的角色（role）和有效时长（lifespan）：

• 角色：包括 admin（管理员）、writer（读写）或 reader（只读）三种角色，每种角色的 Token 具有的权限详见 Token 类型和权限。

• 有效时长：取值为正整数，单位为毫秒。生成 Token 的 UTC 时间加上你设置的有效时长，即 Token 的过期时间。Token 过期后，用户将无法再使用该 Token 加入房间或访问互动白板服务。为确保业务可用性，你需要及时生成新的 Token。

  注意

  • 如果你不设置 Token 的有效时长或将有效时长设为 0，生成的 Token 将永不过期。永不过期的 Token 可能为你的业务带来安全隐患。
  • 已经加入房间的用户不会因为 Token 过期被移出房间。
  • 项目被禁用或删除后，与之关联的访问密钥对也会被禁用或删除，所有使用该访问密钥对生成的 Token 都会失效。

前提条件Copy Anchor Link

开始前，确保你已参考开启和配置互动白板服务完成了以下准备工作：

• 创建一个开启了互动白板服务的声网项目。
• 获取访问密钥 Access Key (AK) 和私有访问密钥 Secret Access Key (SK)。
• 如果你需要生成 Task Token 用于文档转换服务，则需要为项目开启并配置文档转换服务。

实现方法Copy Anchor Link

本节介绍如何调用服务端 API 生成互动白板 Token。

生成 SDK TokenCopy Anchor Link

生成 SDK Token 时，你需要传入项目的 AK 和 SK、Token 的有效时长和角色，详见生成 SDK Token。以 cURL 为例：

curl --request POST \
  --url https://api.netless.link/v5/tokens/teams \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'region: cn-hz' \
  --data '{
  "accessKey": "BUxxxxxxrc",
  "secretAccessKey": "CxxxxxxxauY3",
  "lifespan": 3600000,
  "role": "admin"
}'

生成 Room TokenCopy Anchor Link

生成 Room Token 时，你需要传入房间 UUID、SDK Token、Token 的有效时长和角色，其中房间 UUID 需要调用POST 创建房间获取，详见生成 Room Token。以 cURL 为例：

curl --request POST \
  --url https://api.netless.link/v5/tokens/rooms/9e2xxxxxxxx356 \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'region: cn-hz' \
  --header 'token: NETLESSSDK_xxxxxxxxx' \
  --data '{
  "lifespan": 36000,
  "role": "admin"
}'

生成 Task TokenCopy Anchor Link

生成 Task Token 时，你需要传入转换任务的 UUID、SDK Token、AK、Token 的有效时长和角色，其中转换任务的 UUID 需要调用发起文档转换获取，详见生成 Task Token。以 cURL 为例：

curl --request POST \
  --url https://api.netless.link/v5/tokens/tasks/2fd2dxxxxx367e \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'region: cn-hz' \
  --header 'token: NETLESSSDK_xxxxxx' \
  --data '{
  "role": "writer",
  "lifespan": 36000,
  "ak": "T9xxxxxxxwkk"
}'

相关信息Copy Anchor Link

API 参考Copy Anchor Link

• 生成 SDK Token
• 生成 Room Token
• 生成 Task Token

Token 的类型和权限Copy Anchor Link

本节介绍不同角色的三种 Token 所具有的权限。

SDK TokenCopy Anchor Link

Room TokenCopy Anchor Link

Task TokenCopy Anchor Link

Token 相关错误Copy Anchor Link

在使用 Token 访问互动白板服务时，你可能会遇到以下报错，你可以参考说明进行问题排查。

通过其他方式生成 TokenCopy Anchor Link

除调用服务端 API 生成外，你还可以通过以下方法生成互动白板 Token：

• 在声网控制台生成 SDK Token。
• 在 App 服务端用代码生成 Token，详见在 App 服务端生成 Token。