接口文档

HTTP 状态码总览

错误响应格式

所有 API 错误均返回 JSON，结构如下：

// 用户 API 错误示例（整数错误码）
{"error": 40001, "message": "需提供密码及手机号或邮箱"}
{"error": 40105}

// OAuth2 /oauth/token 错误示例（标准字符串错误码，RFC 6749 §5.2）
{"error": "invalid_grant", "error_description": "授权码不存在或已被消费"}
{"error": "unsupported_grant_type", "error_description": "仅支持 grant_type=authorization_code"}
{"error": "invalid_client", "error_description": "客户端认证失败"}

限流策略

以上 全部 6 项均为必填。
code_verifier 经 SHA-256 后做 base64url 编码（RFC 7636 §4.2，不可先转 hex）应与授权请求中的 code_challenge 匹配。
若授权请求中 code_challenge_method 为 plain，则 verifier 与 challenge 直接字符串比对。
返回的 JWT 包含 cid（第三方 clientId）+ aud（受众），代表第三方代表用户访问。

成功响应 (200)

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "abc123...",
  "scope": "profile"
}

请求示例

POST http://oauth.deitydo.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://yourapp.com/callback
&client_id=cli_abc123
&client_secret=cs_xyz789
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

请求头

成功响应 (200)

{
  "sub": "uuid",
  "username": "user123",
  "phone": "138****0000",
  "email": "user@example.com"
}

请求示例

GET http://oauth.deitydo.com/oauth/userinfo
Authorization: Bearer {access_token}

请求头

成功响应 (200)

{
  "sub": "uuid",
  "username": "user123",
  "phone": "138****0000",
  "email": "user@example.com"
}

请求示例

GET http://oauth.deitydo.com/api/userinfo
Authorization: Bearer {access_token}

成功响应 (200)

{
  "success": true,
  "message": "验证码已发送"
}

请求示例

POST http://oauth.deitydo.com/api/send-code
Content-Type: application/json

{"email":"user@example.com"}

type 为必填项，决定采用哪种注册方式：
· type=email：必须提供 email 与 code（先调用 POST /api/send-code 获取验证码）；
· type=phone：必须提供 phone，无需验证码；
· type=wechat：暂未开放，将返回 40005。
username 为必填项，全局唯一（重复将返回 40901）。
password 与 confirm_password 均为客户端 SHA256 后的 64 位 hex，服务端校验两者一致（不一致返回 40006）。
注册接口无需 Token 认证。client_id 为必填项，注册成功后用户将自动与该第三方应用建立授权绑定。
redirect_uri 为可选参数。必须以该应用在 /partner/apply 注册的某个回调地址为前缀（如注册了 https://yourapp.com/reg，则可填写 https://yourapp.com/reg/dashboard），不匹配返回 40003。

成功响应 (200)

{
  "id": "uuid",
  "username": "alice",
  "phone": "13800000000",
  "email": "user@example.com",
  "redirect_uri": "https://yourapp.com/page-a"   // 仅当入参传入时返回
}

请求示例

POST http://oauth.deitydo.com/api/register
Content-Type: application/json

{"type":"email","username":"alice","email":"user@example.com","code":"123456","password":"a1b2c3...","confirm_password":"a1b2c3...","client_id":"cli_abc123","redirect_uri":"https://yourapp.com/page-a"}

type 为必填项：email / phone 走密码认证；wechat 需携带 access_token 走联合登录。
无需 Token 认证。
此接口完成认证后按 RFC 6749 §4.1.2 以 302 重定向发码（不再返回 JSON 授权码）：重定向到 redirect_uri?code=xxx&state=xxx，授权码通过 Location 查询参数投递，绝不出现在响应体。程序化客户端需以 redirect:"manual" 读取 Location 头。后续步骤：
1) 从 302 的 Location 取出 code
2) 调用 POST /oauth/token（需 client_secret + code_verifier）
3) 获得 access_token + refresh_token

成功响应 (302 Found)

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?code=AUTH_CODE_xxx&state=xyz123
Set-Cookie: user_token=...; HttpOnly; SameSite=Lax        ← SSO 设备会话
Set-Cookie: transfer_token=...; HttpOnly; SameSite=Lax    ← 跨设备 SSO 中转（原 JSON 字段已废弃）

请求示例

POST http://oauth.deitydo.com/api/login
Content-Type: application/json

{"type":"phone","response_type":"code","identifier":"13800000000","password":"a1b2c3...","client_id":"cli_abc123","redirect_uri":"https://yourapp.com/callback","code_challenge":"...","code_challenge_method":"S256","state":"xyz123"}

GET — 授权入口

请求示例

GET http://oauth.deitydo.com/oauth/authorize?response_type=code&client_id=app_xxx&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&code_challenge=abc123...&state=xyz789

成功响应 — ③ SSO 静默 (302)

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?code=AUTH_CODE_xxx&state=xyz789

POST — 处理授权确认

请求示例

POST http://oauth.deitydo.com/oauth/authorize
Content-Type: application/x-www-form-urlencoded

consent=approve&client_id=app_xxx&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&code_challenge=abc123...&state=xyz789

成功响应 — 同意授权 (302)

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?code=AUTH_CODE_xxx&state=xyz789

拒绝授权 (302)

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?error=access_denied&error_description=用户拒绝授权&state=xyz789

刷新接口无需 Token 认证，仅凭 refresh_token 即可换取新的 access_token（JWT 含 aud 声明）。

成功响应 (200)

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

请求示例

POST http://oauth.deitydo.com/api/refresh
Content-Type: application/x-www-form-urlencoded

refresh_token={refresh_token}

成功响应 (200)

Set-Cookie: user_token=; Max-Age=0

{
  "message": "已登出"
}

请求示例

POST http://oauth.deitydo.com/api/logout