令牌端点

POST /oauth/token

用授权码换取 Access Token，或用 Refresh Token 刷新。

响应 Content-Type： application/json; charset=utf-8

频率限制

• 30 次/分钟（基于请求方 IP，非服务器全局限制）
• 超限返回 HTTP 429，响应头包含 Retry-After

---

Authorization Code Grant

用授权码换取 Token。

请求

POST https://id.caellab.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_CALLBACK_URL
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=YOUR_CODE_VERIFIER

公共客户端（应用设置里选了「公共客户端」）不需要 client_secret，只传 client_id 即可，安全性由 PKCE 承担。

也支持 HTTP Basic Auth 传递凭证（仅机密客户端）：

POST https://id.caellab.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_CALLBACK_URL

请求参数

参数	必需	说明
grant_type	是	固定值 authorization_code
code	是	授权码
redirect_uri	是	必须与授权请求中一致
client_id	是	Client ID（Basic Auth 时可省略）
client_secret	机密客户端必需	Client Secret（Basic Auth 时可省略）；公共客户端不校验
code_verifier	授权时带了 code_challenge 就必需	PKCE 验证值，43-128 位 unreserved 字符

处理逻辑

1. 验证 client_id + client_secret（失败返回 401 invalid_client）；公共客户端只验 client_id，跳过密钥
2. 查找授权码（验证 client_id 匹配、未过期）
3. 验证 redirect_uri 与授权时一致
4. 校验 PKCE：授权码绑定了 code_challenge 时必须带 code_verifier，且它的 S256 摘要要与 challenge 一致
5. 删除已使用的授权码（一次性使用）
6. 生成 Access Token（bin2hex(random_bytes(32))）
7. 生成 Refresh Token
8. 存储 SHA-256 哈希到数据库
9. 返回 JSON 响应

PKCE 校验失败不会消耗授权码

code_verifier 不对、格式非法或漏传时报 400，但授权码仍留在原处，用户可以重新换一次。只有校验通过才会删除授权码。

成功响应

{
  "access_token": "a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "g7h8i9j0k1l2...",
  "scope": "openid profile email"
}

错误响应

error	状态码	说明
invalid_client	401	client_id 或 client_secret 错误
invalid_grant	400	授权码无效、已过期、或已使用
invalid_grant	400	code_verifier 校验失败、格式非法，或强制 PKCE 的应用收到了未绑定 code_challenge 的授权码
invalid_request	400	缺少 code / redirect_uri，或该带 code_verifier 却没带
unsupported_grant_type	400	grant_type 不是 authorization_code 或 refresh_token
rate_limited	429	请求太频繁

---

Refresh Token Grant

刷新 Access Token。

请求

POST https://id.caellab.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

请求参数

参数	必需	说明
grant_type	是	固定值 refresh_token
refresh_token	是	Refresh Token
client_id	是	Client ID
client_secret	是	Client Secret

处理逻辑

1. 验证客户端凭证
2. 查找 Refresh Token（验证 client_id 匹配、未撤销、未过期）
3. 撤销旧的 Refresh Token
4. 撤销旧的 Access Token
5. 生成全新的 Access Token + Refresh Token
6. 返回 JSON 响应

Refresh Token 轮换

每次刷新都会使旧的 Refresh Token 失效。请在你的应用中及时保存新的 Refresh Token。

Token 有效期

Token 类型	有效期
Access Token	1 小时
Refresh Token	180 天
Authorization Code	10 分钟

成功响应

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "openid"
}

错误响应

error	状态码	说明
invalid_grant	400	Refresh Token 无效、已过期、或已撤销
invalid_request	400	缺少 refresh_token

---

错误响应格式

所有错误都返回统一格式：

{
  "error": "ERROR_CODE",
  "error_description": "人类可读的错误描述"
}