Omniscol API——身份验证令牌

密钥与令牌：两个不同的对象

Omniscol区分两个不可混淆的对象。

密钥是由Omniscol持久保存的对象，包含：

• 一个随机生成的简短标识符，公开可见：列表中显示的就是它，它也包含在每个令牌中，用于指明需要验证的密钥；
• 一个描述性的名称，可随时修改；
• 一个可选的到期日期，可随时修改；
• 一个由服务器生成的随机长密文，用作加密签名密钥。

标识符、名称和到期日期属于管理信息：标识符只是公开引用，并非机密。密文才是唯一的签名材料：它在创建密钥时随机生成，只保存在服务器端，不可修改，并且从不显示、从不返回——创建时不会，密钥列表中也不会。即使它泄露，也不足以伪造令牌：签名还会结合账户专属的盐值和服务器密文，这两者同样不会离开Omniscol。

令牌是一个独立的JWT（JSON Web Token），用密钥的密文签名。您把它提供给外部系统。其签名内容包含所属账户、授权接入点列表、所派生的密钥，以及令牌自身的到期日期。

换句话说：**密钥负责签名，令牌被签名。**同一个密钥可以签发多个令牌——它们都能用同一个密文验证，因此密钥一旦消失，这些令牌会一并失效。

Omniscol不保存令牌：它生成令牌，只显示一次，之后每次调用时用密钥的密文重新计算签名（HMAC SHA-256）来验证。没有这个密文，令牌所携带的任何授权都无法被篡改。

创建令牌

在Premium账户中，分享 界面位于 管理 → 导入 / 导出。创建分两步：先创建密钥，再用这个密钥生成令牌。

1. 创建密钥——填写一个清晰的名称；如果访问是临时的，再填写到期日期。名称和到期日期之后仍可修改，签名密文则不可修改。
2. 生成令牌——选择密钥，勾选授权的接入点，按需为令牌设置单独的到期日期，然后生成JWT。

生成时，Omniscol只显示令牌一次。请立即把它复制到密钥管理器中：之后不会再次显示。令牌的到期日期写在已签名的内容里，事后无法修改。若要更改该日期，请生成新令牌。

因此有两级相互独立的到期设置：

• 密钥到期——可在密钥列表中修改；到期后，由该密钥派生的所有令牌都会被拒绝（调用返回401）；
• 令牌到期——在生成时确定，写入JWT，之后不可修改。

授权接入点

令牌只能访问生成时勾选的接入点：请勿默认它覆盖整个API。授权列表随令牌一起传递，并在每次调用时验证；调用未授权的接入点会被拒绝（401）。

除了单个接入点，选择列表还提供按模块的快捷选项：

• 单独勾选某个模块的条目，授权该模块的所有接入点；
• 按操作区分的选项——读取、修改、创建、删除——把该模块限定为某一类调用。

例如勾选“课表 [读取]”，即可授予全部课表读取权限而不开放任何写入，无需逐个勾选接入点。请遵循最小授权原则：只授予集成确实需要的模块和操作。

使用令牌

向API发送令牌，常用两种方式：

• HTTP请求头：Authorization: Bearer <令牌>（推荐）。
• 查询字符串：?auth=<令牌>（便于调试，但会出现在HTTP日志中——生产环境请避免使用）。

curl 示例，请替换为OpenAPI中的真实接入点：

curl -H "Authorization: Bearer $TOKEN" \
  https://your-school.omniscol.com/api/<module>/<endpoint>

OpenAPI文档

导入 / 导出界面提供一个OpenAPI 3.1链接，可在Swagger Editor中打开该账户可用的规范。您可以在其中找到：

• 已开放的API接入点列表，
• 交换数据的结构，
• 方法和参数，
• 预期的响应。

规范也由您的账户直接提供，无需身份验证：

• /api/guest/openapi.json——JSON格式的规范；
• /api/guest/openapi.yaml（或 /api/guest/openapi?yaml=true）——相同内容的YAML格式；
• /api/guest/school_schema.json——账户数据的JSON结构。

为您的AI助手提供完整帮助

门户网站还把Omniscol的全部帮助发布为一个文本文件，可直接作为AI助手（Claude项目、自定义GPT等）的知识库：

• omniscol.com/fr/llms-full.txt——Markdown格式的完整指南，提供帮助的每种语言版本（/en/llms-full.txt、/de/llms-full.txt 等）；
• omniscol.com/llms.txt——符合 llms.txt 标准的索引，AI引擎会自动发现。

撤销访问

撤销在密钥层面进行，而不是针对单个令牌。

界面列出用于生成令牌的密钥。删除密钥会清除Omniscol端的签名密文：此后，任何由该密文派生的签名都无法再通过验证，所有出示该密钥所签发令牌的调用都会返回401。令牌失效的原因是密文不存在，而不是因为有一份撤销名单。

对信息化部门而言，有两点需要注意：

• **不支持逐个令牌撤销。**Omniscol不保存已签发的JWT，无法单独停用其中某一个：已生成的令牌在自身到期之前一直有效，或者直到其密钥被删除或到期。
• 修改密钥的到期日期会立即影响其所有令牌：把该日期提前，会切断该密钥所有令牌的访问。

最佳实践：一旦怀疑某个密钥泄露，请立即删除，然后重新创建一个名称清晰的替代密钥。

每个目标系统、每种用途一个密钥

由于撤销以密钥为单位，请为每个集成单独使用一个密钥（一个外部软件对应一个密钥）。密钥的密文只为它自己的令牌签名：删除该密钥只会使相应集成的访问失效，不影响其他集成。

反之，如果多个系统共用同一个密钥，任何撤销都会很突兀：删除被泄露的密钥，会一次性切断所有使用它的系统。

适用的集成

API通常用于：

• 定制的信息显示系统（超出Omniscol原生信息显示屏的范围；参见 显示屏的自定义），
• 整合Omniscol与其他数据源的外部仪表盘，
• 与ERP或业务信息系统的连接器或同步，
• 通过MCP服务器使用Omniscol的兼容MCP的AI智能体；参见 MCP——连接外部AI智能体。

如果需要向已识别的第三方服务提供委托访问（限定范围的令牌、用户授权，停用客户端即可撤销），请优先使用Omniscol的OAuth2服务器：参见 OAuth2 / OIDC（提供方）。