OAuth 2.0 接入文档
概述
智穗语聊 OAuth 2.0 允许第三方应用使用智穗语聊账号进行用户登录。用户授权后，您的应用可以获取用户的基本信息。
API 基础地址： https://api.zhsidc.com
应用凭证说明
App ID（应用标识）
相当于应用的"用户名"，是公开的标识符。用于在授权请求中告诉服务器"这是哪个应用在请求授权"。
- 可以公开，无安全风险
- 用于授权页面 URL 的
app_id参数
App Secret（应用密钥）
相当于应用的"密码"，用于证明请求确实来自你的应用。必须严格保密！
- 只能存储在你的服务器后端，禁止暴露在前端代码
- 用于服务端换取用户信息时的身份验证
- 泄露后应立即重新生成
⚠️ 安全提示：App Secret 只在创建应用时显示一次。如果泄露或遗忘，请在应用详情页重新生成。
授权流程
┌─────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ 你的网站 │ │ 智穗语聊服务器 │ │ 智穗语聊客户端 │
└─────────────┘ └──────────────────┘ └──────────────────┘
│ │ │
│ 1. 跳转授权页面 │ │
│ ────────────────────>│ │
│ (app_id, redirect_uri) │
│ │ 2. 检测登录状态 │
│ │ ──────────────────────>│
│ │ │
│ │<────────────────────── │
│ │ 返回用户信息(id,头像等) │
│ │ │
│ 用户点击头像确认授权 │
│ │ │
│ 3. 回调并携带 token │ │
│<──────────────────── │ │
│ │ │
│ 4. 用 token+secret │ │
│ 获取用户信息 │ │
│ ────────────────────>│ │
│ │ │
│<──────────────────── │ │
│ 返回用户数据 │ │
│ │ │1
引导用户授权
将用户重定向到授权页面，用户需要打开智穗语聊客户端并登录。
2
用户确认授权
授权页面会自动检测客户端登录状态，用户点击头像即可确认授权。
3
获取一次性 Token
授权成功后，用户被重定向回你的回调地址，URL 中携带 token 参数。
4
换取用户信息
在你的服务器后端，使用 Token + App Secret 调用 API 获取用户信息。
API 接口
GET
/oauth/authorize打开授权页面，引导用户授权登录
请求参数
| 参数 | 必填 | 说明 |
|---|---|---|
| app_id | 是 | 你的应用 App ID |
| redirect_uri | 是 | 授权成功后的回调地址（需与应用配置一致） |
| state | 推荐 | 随机字符串，用于防止 CSRF 攻击，会原样返回 |
| scope | 否 | 授权范围：userinfo 或 userinfo,email |
示例
https://api.zhsidc.com/oauth/authorize ?app_id=zs_xxxxxxxxxxxxxxxx &redirect_uri=https://example.com/callback &state=random_string_123 &scope=userinfo,email
回调参数
授权成功后，用户会被重定向到：
https://example.com/callback?token=xxxxxxxxxxxx&state=random_string_123
POST
/oauth/token使用 Token 和 App Secret 换取用户信息（必须在服务端调用）
请求参数
| 参数 | 必填 | 说明 |
|---|---|---|
| app_id | 是 | 你的应用 App ID |
| app_secret | 是 | 你的应用 App Secret |
| token | 是 | 回调获得的一次性 Token（3分钟内有效，只能用一次） |
请求示例
curl -X POST https://api.zhsidc.com/oauth/token \
-H "Content-Type: application/json" \
-d '{
"app_id": "zs_xxxxxxxxxxxxxxxx",
"app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"token": "回调获得的token"
}'成功响应
{
"user_id": 12345,
"zs_number": 100000001,
"username": "zhangsan",
"nickname": "张三",
"avatar": "/uploads/avatars/xxx.jpg",
"email": "zhangsan@example.com"
}错误响应
{
"error": "invalid_token",
"message": "Token无效或已过期"
}
{
"error": "invalid_client",
"message": "App ID 或 App Secret 错误"
}快速开始（PHP 示例）
1. 登录按钮（前端）
<a href="https://api.zhsidc.com/oauth/authorize?app_id=你的AppID&redirect_uri=https://你的网站/callback.php&scope=userinfo,email"> 使用智穗语聊登录 </a>
2. 回调处理（后端 callback.php）
<?php
// 配置信息（App Secret 必须保密，只能放在后端！）
$app_id = '你的AppID';
$app_secret = '你的AppSecret';
// 获取回调参数
$token = $_GET['token'] ?? '';
$state = $_GET['state'] ?? '';
if (empty($token)) {
die('授权失败：未获取到 token');
}
// 调用 API 换取用户信息
$response = file_get_contents('https://api.zhsidc.com/oauth/token', false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => 'Content-Type: application/json',
'content' => json_encode([
'app_id' => $app_id,
'app_secret' => $app_secret,
'token' => $token
])
]
]));
$user = json_decode($response, true);
if (isset($user['error'])) {
die('获取用户信息失败：' . $user['message']);
}
// 登录成功！
echo '欢迎，' . htmlspecialchars($user['nickname']);
echo '<br>智穗号：' . $user['zs_number'];
echo '<br>用户名：' . htmlspecialchars($user['username']);
// 在这里创建你网站的登录会话...
// $_SESSION['user_id'] = $user['user_id'];
?>常见问题
Q: App Secret 可以放在前端吗？
绝对不可以！App Secret 相当于应用的密码，必须只存在于你的服务器后端。 前端代码（HTML/JS）可以被用户查看，Secret 泄露会导致他人可以伪装成你的应用。
Q: Token 有效期多长？
Token 有效期为 3 分钟，且只能使用一次。请在收到 Token 后立即在服务端调用 API 换取用户信息。
Q: 用户需要安装智穗语聊客户端吗？
是的，用户需要安装并登录智穗语聊客户端。授权页面会自动检测本地客户端的登录状态，类似于 QQ 快捷登录的方式。
Q: App Secret 泄露了怎么办？
请立即登录开发者中心，进入应用详情页，点击"重新生成密钥"按钮。旧密钥将立即失效。
Q: redirect_uri 有什么限制？
回调地址必须与创建应用时填写的一致，这是为了防止恶意网站截取授权 Token。