首页 > 开发者文档
接入文档
VOBL ID 实现的是标准 OAuth 2.0 授权码流程，并要求 PKCE。 任何已有的 OAuth 2.0 客户端库都可以直接对接，不需要专用 SDK。
端点清单
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/.well-known/oauth-authorization-server | 发现文档（建议程序读取，不要硬编码） |
| GET | /authorize | 授权页，浏览器跳转到这里 |
| POST | /api/oauth/token | 授权码换访问令牌 |
| GET | /api/oauth/userinfo | Bearer 令牌换用户信息 |
接入流程
1. 在控制台创建应用
登录控制台 →「应用管理」→ 新建应用，得到 client_id；
机密应用还会得到一次性显示的 client_secret，请立即保存。
2. 发起授权（带 PKCE）
GET /authorize ?response_type=code &client_id=vobl_xxxxxxxx &redirect_uri=https%3A%2F%2Fyour.app%2Fauth%2Fcallback &scope=profile%20email &state=随机防重放串 &code_challenge=BASE64URL(SHA256(verifier)) &code_challenge_method=S256
state必须校验回传值是否一致；code_challenge用 S256。 授权码有效期 120 秒，且只能使用一次——重放会被拒绝。
3. 换取访问令牌
POST /api/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=上一步拿到的授权码 &client_id=vobl_xxxxxxxx &client_secret=机密应用必填 &redirect_uri=必须与授权时完全一致 &code_verifier=与 challenge 对应的原始串
返回 access_token（有效期 3600 秒）、token_type=Bearer、scope。
4. 读取用户信息
GET /api/oauth/userinfo Authorization: Bearer <access_token>
返回内容按申请的 scope 裁剪：profile 给昵称与头像，
email 给邮箱与验证状态，orgs 给角色列表。
身份标识请用 sub（用户 ID），不要用邮箱——邮箱可以更换。
错误码
| error | 含义与处理 |
|---|---|
| invalid_grant | 授权码无效、已过期或已被使用。重新发起授权，不要重试同一个码。 |
| invalid_client | client_id 或 client_secret 不对。检查是否填反、或密钥已重置。 |
| invalid_token | 访问令牌无效或已过期（1 小时）。用 refresh 或重新走授权流程。 |
| unsupported_grant_type | 目前只支持 authorization_code。 |
常见坑
- redirect_uri 必须精确匹配白名单——包括结尾斜杠与查询串。不做模糊匹配是安全设计，不是 bug。
- 机密应用务必在服务端换令牌——
client_secret一旦出现在前端就等于公开。 - 用 sub 而不是邮箱做用户唯一标识。
- 授权码一次性：网络重试时不要复用旧码，要重新走一次授权。
- 不签发 id_token：本项目是纯 OAuth 2.0，不是完整 OIDC。需要 JWT 时请在服务端用 userinfo 端点取身份。