创建 API 令牌

通过 API 令牌，集成（例如与学习管理系统的同步）可以访问您工作区的 /api/v1 接口。令牌以拥有者的权限运行，并受其作用域的进一步限制。

开始之前

• 您在 Hub 中拥有 管理工作区 任务。Fracto 支持人员看不到 API 令牌 选项卡。
• 令牌将属于创建它的人，也就是您。它使用您当前的权限运行。每个请求还会检查您是否仍有权执行该操作。因此，不要使用将来会失去任务的账户创建令牌。
• 考虑集成需要哪些作用域，并仅选择这些作用域。

如何创建令牌

1. 在 Hub 中，打开 组织 和 API 令牌 选项卡。

2. 点击 创建令牌。

3. 输入 标签，例如“LMS 同步”（最多 120 个字符）。

4. 在 作用域 下，打开令牌可以执行的操作。每个作用域都有一个开关，其下方有简短代码，例如 certificates:read。默认未选择任何内容，至少需要一个作用域。列表包含 14 个作用域，包括读取课程、编辑课程草稿、注册学员、读取证书、读取人员、邀请和管理人员以及管理制造商工作区。对于人员、组织、制造商工作区和注册，写入作用域包含匹配的读取作用域。最终，只有您的权限允许的内容才会生效。

   

   查看英文界面

5. 在 到期日期（可选） 下，您可以选择一个日期。令牌将在您工作区时区的该日期结束时保持有效。如果没有设置日期，则令牌在撤销前一直有效。

6. 点击 创建令牌。仅当设置了标签和至少一个作用域时，该按钮才会变为可用。

7. 在 复制令牌密钥 窗口中，点击密钥旁边的 复制，并将密钥安全存储，例如存储在集成的设置中。Fracto 不会再次显示它。然后点击 完成。

   

   查看英文界面

集成在每次向 /api/v1 发出请求时，将密钥作为 Bearer 令牌发送到 Authorization 标头中。在生产环境中，它以 frt_live_ 开头。

如何知道它已生效

令牌会出现在列表中，状态为 活动，您为 所有者。令牌 列显示标签，其下方显示密钥的前几个字符（前缀）。作用域 以简短代码形式显示作用域。最后使用 显示“从未”，直到集成首次使用它。因缺少权限而被拒绝的请求也会计入此处。

轮换、撤销、历史记录

• 轮换 仅对活动令牌的所有者显示。Fracto 会撤销旧令牌，并创建一个具有相同标签、相同作用域和相同到期日期的新令牌。它会像创建时一样显示一次新密钥。请立即在集成中输入它。
• 任何管理员都可以 撤销 任何活动令牌。Fracto 会询问：“令牌将停止工作。此操作无法撤销。”
• 历史记录 显示谁创建、轮换或撤销了令牌，以及时间。最多显示最近 100 个事件。

后续步骤

• 令牌以其所有者当时的权限运行。如果权限缺失，接口会以 403 ACCESS_DENIED 拒绝请求。当某人失去任务或工作访问权限结束时，Fracto 不会撤销令牌。对于人员保留的权限（例如来自 Channel 或 Campus 的预约），令牌将继续工作，并且在恢复或收到新邀请后，它将完全恢复工作。因此，请自行撤销令牌，请参阅 移除或暂停访问。
• 到期日期后，Fracto 不再接受该令牌。列表仍会将其显示为 活动，直到有人在到期后使用它。只有那时才会显示 已过期。
• 创建、轮换和撤销仅出现在令牌的历史记录中，不会出现在活动日志中。

如果它不起作用

消息	含义
您没有此操作的权限。只有所有者可以轮换令牌。	出现在您缺少任何操作权限时，例如因为您的任务在此期间已更改。文本始终提到轮换。只有所有者能看到 轮换。
操作失败。请重试。	轮换、撤销或历史记录未生效。请重试，例如如果令牌在此期间已被撤销。
无法加载 API 令牌。	重新加载页面。

接口本身会返回以下错误：authentication_required（无或格式错误的 Bearer 令牌）、invalid_token（令牌无效、已过期或已撤销）、insufficient_scope（令牌缺少所需作用域）、ACCESS_DENIED 状态码 403（所有者缺少操作权限，这是访问被移除后最常见的情况）以及 workspace_mismatch（对于带有工作区的地址：令牌属于另一个工作区）。