API 详细文档

本文档详细描述墨觉互联 OAuth2 开放平台的所有接口，包括请求参数、返回值和错误码。

接口列表

接口	地址	方法	说明
授权端点	`/oauth/authorize.php`	GET	引导用户授权，获取授权码
令牌端点	`/oauth/token.php`	POST	用授权码换取令牌，或刷新令牌
用户信息端点	`/oauth/userinfo.php`	GET	使用access_token获取用户信息

1. 授权端点

地址：GET http://auth.mojue88.com/oauth/authorize.php

该接口用于引导用户进行授权。用户在浏览器中访问该地址，登录并同意授权后，将重定向到应用的回调地址。

请求参数

参数名	类型	必填	说明
client_id	string	是	应用的 AppID
redirect_uri	string	是	授权回调地址，必须与应用配置的白名单前缀匹配
response_type	string	是	固定值：`code`
state	string	推荐	客户端状态值，用于防止CSRF攻击，回调时原样返回
scope	string	否	授权范围，默认 `basic`。可选：`basic`、`basic+email`、`profile`

授权范围说明

scope值	可获取的用户信息
basic	openid、username、nickname、avatar
basic+email	basic的所有字段 + email
profile	basic的所有字段 + bio、registered_at

成功响应

用户同意授权后，重定向到 redirect_uri，URL中携带以下参数：

参数名	类型	说明
code	string	授权码，有效期10分钟，只能使用一次
state	string	请求时传入的state参数（如果有）

失败响应

用户拒绝授权或发生错误时，重定向到 redirect_uri，URL中携带：

参数名	说明
error	错误码，如 `access_denied`
state	请求时传入的state参数（如果有）

2. 令牌端点

地址：POST http://auth.mojue88.com/oauth/token.php

Content-Type：application/x-www-form-urlencoded

该接口支持两种 grant_type：authorization_code（用授权码换取令牌）和 refresh_token（刷新令牌）。

2.1 授权码模式

请求参数

参数名	类型	必填	说明
grant_type	string	是	固定值：`authorization_code`
client_id	string	是	应用的 AppID
client_secret	string	是	应用的 AppSecret
code	string	是	授权端点返回的授权码
redirect_uri	string	是	必须与授权时的 redirect_uri 完全一致

2.2 刷新令牌模式

请求参数

参数名	类型	必填	说明
grant_type	string	是	固定值：`refresh_token`
client_id	string	是	应用的 AppID
client_secret	string	是	应用的 AppSecret
refresh_token	string	是	之前获取的刷新令牌

成功响应

{
  "access_token": "at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "rt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "basic",
  "openid": "uid_1_xxxxxxxxxxxxxxxx"
}

字段	类型	说明
access_token	string	访问令牌，有效期7200秒（2小时）
token_type	string	固定值：Bearer
expires_in	int	access_token 有效期（秒）
refresh_token	string	刷新令牌，有效期30天
scope	string	实际授权范围
openid	string	用户在当前应用下的唯一标识

3. 用户信息端点

地址：GET http://auth.mojue88.com/oauth/userinfo.php

使用 access_token 获取当前授权用户的信息。

请求方式

推荐在 HTTP Header 中携带：

Authorization: Bearer ACCESS_TOKEN

也支持通过 GET 参数传递（不推荐，可能被日志记录）：

GET /oauth/userinfo.php?access_token=ACCESS_TOKEN

成功响应

{
  "openid": "uid_1_xxxxxxxxxxxxxxxx",
  "username": "zhangsan",
  "nickname": "张三",
  "avatar": "https://example.com/avatar.png",
  "email": "zhangsan@example.com",
  "bio": "这是我的个人简介",
  "registered_at": "2026-01-01 12:00:00"
}

字段	类型	说明	scope要求
openid	string	用户在当前应用下的唯一标识	basic
username	string	用户名	basic
nickname	string	用户昵称	basic
avatar	string	头像URL	basic
email	string	邮箱地址	basic+email
bio	string	个人简介	profile
registered_at	string	注册时间	profile

错误码说明

所有接口在发生错误时，返回如下格式的JSON：

{
  "error": "invalid_request",
  "error_description": "缺少必要参数"
}

错误码	HTTP状态码	说明	常见原因
invalid_request	400	请求参数无效	缺少必填参数、参数格式错误
invalid_client	401	客户端验证失败	AppID不存在、AppSecret错误、应用未通过审核、应用被封禁
invalid_grant	400	授权码或刷新令牌无效	授权码已使用/过期、redirect_uri不匹配、refresh_token无效/过期
unsupported_grant_type	400	不支持的授权类型	grant_type 不是 authorization_code 或 refresh_token
invalid_token	401	访问令牌无效	access_token 不存在、已过期、已撤销
access_denied	401/302	访问被拒绝	用户拒绝授权、用户账号被封禁
server_error	500	服务器内部错误	数据库异常等服务端问题

注意事项

AppSecret 安全：AppSecret 必须保存在服务端，绝不能出现在客户端代码（前端JS、APP安装包等）中。
HTTPS：生产环境强烈建议使用 HTTPS，防止令牌在传输过程中被窃取。
state 参数：强烈建议使用 state 参数防止 CSRF 攻击，回调时验证 state 是否一致。
授权码一次性：授权码 code 只能使用一次，且有效期为10分钟，请及时换取令牌。
令牌存储：access_token 和 refresh_token 应安全存储在服务端，不要暴露给客户端。
应用状态：只有状态为「已通过」的应用才能使用OAuth2服务，待审核/已拒绝/已封禁的应用调用接口将返回 invalid_client 错误。