API令牌

API令牌（token）允许第三方软件以学校的名义调用Omniscol的API接口：可读取数据；若选择了写入类API接口，也可写入数据。

它的权限很大，因此请谨慎使用。

生成

令牌在分享中生成（导入/导出 > 分享）。您需要提供：

• 一把密钥（在Omniscol中生成，带有名称和可选的有效期；有效期日后可以修改），
• 一个范围：该令牌可以调用的API接口列表（只授予确实需要的接口），
• 可选的令牌有效期。该日期写入生成的JWT，之后无法修改。

删除密钥或密钥到期，会立即撤销由它派生的所有令牌。若要更改某个令牌的有效期，请重新生成一个JWT。

使用

令牌通过HTTP请求头Authorization: Bearer <token>传递，也可以通过URL中的?auth=<token>传递（生产环境不推荐）。

最佳实践

• 一个集成一把密钥——便于单独撤销。
• 最小范围——只勾选必需的API，不要默认全选。
• 在合适的层级设置有效期——长期运行的集成用密钥的有效期来管理；需要不可更改的临时访问时，使用令牌的有效期。
• 定期轮换——每6至12个月重新生成一次密钥。
• 不要放进Git——令牌不应被纳入公开代码仓库的版本管理。请使用服务器的环境变量。

与OIDC / SSO的区别

若要让真实用户使用所在机构的身份登录，请使用OIDC / SSO。API令牌用于服务器之间的技术集成，不用于用户的日常登录。