OAuth 授权协议
本文介绍如何通过 OAuth 2.0 Client Credentials 模式获取并使用 Access Token 访问希悦开放平台 API，并给出常见问题与最佳实践建议。
场景概述
- 使用方需要以“系统后端到开放平台后端”的方式获取数据（无终端用户交互）。
- 平台发放
client_id与client_secret（下文统称“凭证”）。 - 通过凭证换取短期有效的
access_token，随后在调用业务 API 时放入Authorization头部。
如果还未领取凭证，请联系平台工作人员。请妥善保管 client_secret，不要提交到公开版本库或前端代码中。
授权流程一览
- 后端安全环境保存
client_id/client_secret。 - 发送授权请求到 Token 颁发接口（POST /oauth/tokens）。
- 解析返回 JSON，得到
token_type（通常为 Bearer）、access_token、expires_in（秒）。 - 在后续业务请求中设置：
Authorization: Bearer <access_token>X-School-Id: <学校ID>（除授权接口外的所有业务接口必需）
- Token 过期前（例如剩余 <5% 生命周期时）主动刷新，避免临界请求失败。
获取 Access Token
接口地址：
POST https://open.seiue.com/api/v3/oauth/tokens
请求头：
Content-Type: application/json
请求体参数：
| 字段 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| grant_type | string | 是 | client_credentials | 固定填 client_credentials |
| client_id | string | 是 | your-client-id | 平台分配 |
| client_secret | string | 是 | your-secret | 平台分配，务必保密 |
| scope | string | 否 | school.[school_id] klass.read user.read 等 | 以空格分隔的权限集合，留空没有权限 |
Curl 示例
curl 'https://open.seiue.com/api/v3/oauth/tokens' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "client_credentials",
"client_id": "your client id",
"client_secret": "your secret",
"scope": "klass.read user.read"
}'
响应示例
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "<省略>"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| token_type | string | Token 类型（目前为 Bearer） |
| expires_in | number | Token 剩余有效期（秒） |
| access_token | string | 实际用于鉴权的 Token 内容 |
在业务请求中使用 Token
业务接口除个别匿名接口外都需要：
Authorization头：Bearer <access_token>X-School-Id头：指定学校ID
示例：
curl 'https://open.seiue.com/api/v3/klass/classes' \
-H 'X-School-Id: 51' \
-H 'Authorization: Bearer <access_token>'
缓存与续期策略
- 建议将
access_token与过期时间缓存在内存或分布式缓存（Redis）。 - 续期阈值：
now > (issued_at + expires_in - 安全缓冲)；缓冲可取 300 秒或expires_in * 0.05中较小者。 - 同步刷新：使用互斥（分布式锁）避免并发重复申请。
安全最佳实践
- 仅在服务端保存
client_secret，不要下发到浏览器或移动端。 - 强制使用 HTTPS（已有 https://open.seiue.com）。
- 最小授权：scope 只申请必需权限；未使用的 scope 清理。
- 日志脱敏：不要完整打印
access_token/client_secret，可只保留前 6 + 后 4 位。 - 避免硬编码：通过环境变量或配置中心管理凭证。