身份验证：API 密钥与 OAuth
更新于 27.10.2026
在空气污染指数VISH，有三种方法可以访问该方法：不登录，使用API密钥和使用oauth令牌从“通过登录VISH”. 选择哪一个取决于 谁的 您正在阅读的数据和 谁 正在运行程序。 于2026年10月23日与摊位d1核对。
选择什么
| 无需登录 | API密钥 | OAuth令牌（“透过VISH”) | |
|---|---|---|---|
| 什么是 | 开放数据：时间表、小组、教师、教室 | 你的脚本，机器人，上传，仪表板 | 您的网站或应用程序，包括其他人 |
| 代表谁 | 不代表任何人 | 代表您，在钥匙的权利范围内 | 代表登录者，经其同意 |
| 如何是 | 传送来的 — | 标题X-Api-Key: vish_… | 标题Authorization: Bearer … |
| 什么是允许的 | 公共方法GET | 钥匙和你的角色所允许的一切 | 方法短列表中的只读 |
| Срок | — | До даты в ключе (выпущенный себе — не дольше 730 дней) | 15 минут, дальше обновление токеном refresh |
| 哪里有 | d1及制作 | d1及制作 | 到目前为止只有d1 |
如果您不需要阅读任何个人内容，请不要登录：更少的秘密，更少的风险。
API密钥
密钥是在“应用程序中的开发人员页面。 为”更多信息，请参阅API和访问密钥页。 关键从vish_并在单独的标头中传递。:
bash
curl -H "X-Api-Key: $VISH_API_KEY" "$VISH_API/auth/me"
- 带有密钥的请求就是请求 代表你，但仅在颁发密钥时指定的权限范围内。 什么不在集合中，密钥将被拒绝，即使你有权自己这样做。 如果您的角色的权限后来减少，密钥也会立即从下一个请求中丢失它们。
- 密钥在标题中, 永远不要在地址里：地址在日志，浏览器历史记录和标题中结束
Referer. - 如果钥匙和
Authorization在请求中，密钥被计数。 - 有些方法仅适用于应用程序中的人：您的密钥，个人笔记，同意，帐户删除。 你不能用钥匙打电话给他们-答案是403
SESSION_REQUIRED. - 重新发出出现在某处的钥匙“补发”按钮上的“开发人员”页：旧行立即停止工作。
检查密钥，看看它允许做什么。:
// Who the key acts as, and which permissions it carries.
const API = process.env.VISH_API ?? 'https://d1.vish-app.ru/api/v1'
const KEY = process.env.VISH_API_KEY
if (!KEY) throw new Error('set VISH_API_KEY')
const response = await fetch(`${API}/auth/me`, { headers: { 'X-Api-Key': KEY } })
const me = await response.json()
if (!response.ok || !me.id) throw new Error(`HTTP ${response.status}: ${JSON.stringify(me)}`)
console.log('role:', me.role)
console.log('permissions:', me.permissions.length ? me.permissions.join(', ') : '(none: public reads only)')OAuth令牌
访问令牌允许您“登入VISH”：一个人登录到您的应用程序与帐户VISH并允许他们访问。 如何启用它是在登入VISH对于开发人员页。 以下是令牌与密钥的不同之处。:
- 在header中传递
Authorization: Bearer <access_token>. - 它起作用 代表登录者，但只为 阅读 并且仅适用于授予权限调用的方法。:
schedule:read—GET /schedule,GET /schedule/subscriptions/mine,GET /schedule/{id}/subscription;notes:read—GET /schedule/{id}/notes. 任何其他方法将回答403OAUTH_SCOPE_INSUFFICIENT. - 员工或管理员权限（如果有人拥有）不会转移到令牌。
- 它的寿命为15分钟;一个新的接收与刷新令牌（30天，每次更新都会更改）。
- 浏览器不允许您从另一个站点上的页面读取对此类请求（CORS）的响应：使用服务器中的令牌调用计划方法。 只有协议地址
/oauth/…可从浏览器获得。 - 一个人可以在禁用您的应用程序“设置” → “查阅资料” → “连接的令牌应用程序”从下一个请求停止工作。
登录到应用程序本身
申请表格VISH通过Telegram或MAX登录并接收其不记名令牌。 此输入适用于应用程序中的人员，而不适用于集成：不要尝试从脚本中重复它。 脚本需要一个密钥，而其他人的网站需要“登入VISH”.
登录错误
| HTTP | error.code | 发生了什么事 |
|---|---|---|
| 401 | AUTH_REQUIRED | 该方法需要登录，但没有密钥或令牌 |
| 401 | UNAUTHORIZED | 密钥不正确，已撤销，已过期，或其所有者不再存在 |
| 401 | ACCESS_TOKEN_INVALID | Bearer—令牌无效或过期-更新它 |
| 403 | SESSION_REQUIRED | 附录中的人类唯一方法 |
| 403 | OAUTH_SCOPE_INSUFFICIENT | OAuth令牌不允许使用此方法 |
| 403 | FORBIDDEN | 缺少的权利-见访问权限(RBAC) |
失败是什么样子的-没有真正的密钥，具有明显不正确的值:
// A made-up key and a made-up bearer token are both refused with 401.
const API = process.env.VISH_API ?? 'https://d1.vish-app.ru/api/v1'
const attempt = async (headers) => {
const response = await fetch(`${API}/auth/me`, { headers })
return { status: response.status, code: (await response.json()).error?.code }
}
const key = await attempt({ 'X-Api-Key': 'vish_not_a_real_key' })
const bearer = await attempt({ Authorization: 'Bearer not-a-real-token' })
if (key.status !== 401 || key.code !== 'UNAUTHORIZED') throw new Error(`key: ${JSON.stringify(key)}`)
if (bearer.status !== 401 || bearer.code !== 'ACCESS_TOKEN_INVALID') throw new Error(`bearer: ${JSON.stringify(bearer)}`)
console.log('made-up key ->', key.status, key.code)
console.log('made-up token ->', bearer.status, bearer.code)试试吧：下面的方法将在没有钥匙的情况下回答401，并将你的钥匙放在“API密钥”场，它会回答你的数据。 密钥仅保留在此选项卡中，不会保存在任何地方。
试一试请求
只有带锁的方法需要密钥。密钥只保存在本页：不会被存储，只作为本次请求的请求头发送，离开页面后即被清除。 如何获取密钥
验证:2026-10,PWA aa337c45,平台bff65fce._