OAuth2 集成指南

OAuth2 允许第三方应用在用户授权后访问其 MindVerse 数据。本指南介绍如何实现标准的授权码流程。

概述

SecondMe API 使用标准的 OAuth2 授权码流程 (Authorization Code Flow)：

用户被重定向到 MindVerse 授权页面
用户确认授权
MindVerse 返回授权码到你的应用
你的应用用授权码换取 Access Token
使用 Access Token 调用 API

前提条件

在开始之前，你需要：

在 MindVerse SecondMe后台注册应用
获取 client_id 和 client_secret
配置回调 URL (Redirect URI)

令牌类型和有效期

令牌类型	前缀	有效期
Authorization Code	`lba_ac_`	5 分钟
Access Token	`lba_at_`	2 小时
Refresh Token	`lba_rt_`	30 天

授权流程

步骤 1: 发起授权请求

引导用户访问 MindVerse 授权页面。你的服务端需要调用授权接口：

curl -X POST "https://app.mindos.com/gate/lab/api/oauth/authorize/external" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your_client_id",
    "redirectUri": "https://your-app.com/callback",
    "scope": ["user.info", "chat"],
    "state": "random_state_for_csrf_protection"
  }'

请求参数:

参数	类型	必需	说明
clientId	string	是	应用的 Client ID
redirectUri	string	是	授权后的回调 URL
scope	string[]	是	请求的权限列表
state	string	否	CSRF 保护参数，建议使用

成功响应:

{
  "code": 0,
  "data": {
    "code": "lba_ac_xxxxx...",
    "state": "random_state_for_csrf_protection"
  }
}

步骤 2: 用授权码换取 Token

收到授权码后，在服务端用授权码换取 Access Token：

curl -X POST "https://app.mindos.com/gate/lab/api/oauth/token/code" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=lba_ac_xxxxx..." \
  -d "redirect_uri=https://your-app.com/callback" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

请求参数:

参数	类型	必需	说明
grant_type	string	是	固定值 `authorization_code`
code	string	是	步骤 1 获取的授权码
redirect_uri	string	是	必须与步骤 1 中的值一致
client_id	string	是	应用的 Client ID
client_secret	string	是	应用的 Client Secret

成功响应:

{
  "code": 0,
  "data": {
    "accessToken": "lba_at_xxxxx...",
    "refreshToken": "lba_rt_xxxxx...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "scope": ["user.info", "chat"]
  }
}

步骤 3: 使用 Access Token

在 API 请求中使用 Access Token：

curl -X GET "https://app.mindos.com/gate/lab/api/secondme/user/info" \
  -H "Authorization: Bearer lba_at_xxxxx..."

步骤 4: 刷新 Access Token

当 Access Token 过期时，使用 Refresh Token 获取新的 Access Token：

curl -X POST "https://app.mindos.com/gate/lab/api/oauth/token/refresh" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=lba_rt_xxxxx..." \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

请求参数:

参数	类型	必需	说明
grant_type	string	是	固定值 `refresh_token`
refresh_token	string	是	之前获取的 Refresh Token
client_id	string	是	应用的 Client ID
client_secret	string	是	应用的 Client Secret

成功响应:

{
  "code": 0,
  "data": {
    "accessToken": "lba_at_new_token...",
    "refreshToken": "lba_rt_new_token...",
    "tokenType": "Bearer",
    "expiresIn": 7200,
    "scope": ["user.info", "chat"]
  }
}

注意: 刷新 Token 时会同时轮换 Refresh Token，旧的 Refresh Token 将失效。

权限 (Scope)

请求授权时需要指定权限列表。用户可以看到你的应用请求的权限，并决定是否授权。

权限	说明
`user.info`	访问用户基础信息（姓名、邮箱、头像等）
`user.info.shades`	访问用户兴趣标签
`user.info.softmemory`	访问用户软记忆
`note.add`	添加笔记和记忆
`chat`	访问聊天功能

最佳实践: 只请求必要的权限，避免请求过多权限导致用户拒绝授权。

错误处理

授权码无效或过期

{
  "code": 400,
  "message": "授权码无效或已过期",
  "error_code": "oauth2.code.invalid"
}

Client Secret 错误

{
  "code": 401,
  "message": "Client Secret 不匹配",
  "error_code": "oauth2.client.secret_mismatch"
}

Redirect URI 不匹配

{
  "code": 400,
  "message": "Redirect URI 不匹配",
  "error_code": "oauth2.redirect_uri.mismatch"
}

Access Token 过期

{
  "code": 401,
  "message": "Access Token 已过期",
  "error_code": "oauth2.token.expired"
}

安全最佳实践

1. 保护 Client Secret

Client Secret 必须保密，只能在服务端使用，不要在客户端代码中暴露。

2. 使用 State 参数

始终使用 state 参数防止 CSRF 攻击：

import secrets

# 生成随机 state
state = secrets.token_urlsafe(32)
# 存储到 session
session['oauth_state'] = state

# 授权回调时验证
if request.args.get('state') != session.get('oauth_state'):
    raise SecurityError("State mismatch")

3. 验证 Redirect URI

确保 Redirect URI 使用 HTTPS，并且已在SecondMe后台注册。

4. 安全存储 Token

服务端存储时加密 Token
不要在日志中记录 Token
设置合适的过期时间

下一步

OAuth2 API 参考 - 查看完整 API 规格
SecondMe API 参考 - 了解可用的 API 接口
错误码参考 - 了解所有错误码

OAuth2 集成指南

On this page