OAuth 集成

袋袋实现了标准的 OAuth 2.0 Authorization Code 流程，允许你的 App 代表用户调用袋袋 API。通过 OAuth 授权，积分将从用户的账户中扣除。

流程概览

┌──────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐
│ 用户 │────→│ 你的 App │────→│ 袋袋授权│────→│ 用户授权 │
└──────┘     └─────────┘     │   页面   │     │   同意   │
                             └──────────┘     └────┬─────┘
                                                   │
     ┌─────────┐     ┌──────────┐     ┌────────────┘
     │ 调用 API │←───│ 换取Token│←───│ 授权码回调
     └─────────┘     └──────────┘     └────────────

第一步：注册 App

在袋袋 Studio 中创建你的 App：

进入 app.profy.cn/studio
创建一个新的 App
在 App 设置中配置 OAuth 相关信息：
- Client ID：自动生成的 App UUID
- Client Secret：在设置中生成（SHA-256 哈希存储，仅展示一次）
- Redirect URIs：注册你的回调地址（支持多个）

Client Secret 仅在生成时展示一次，请妥善保存。Redirect URI 必须严格匹配注册列表中的地址，否则授权会被拒绝。

第二步：引导用户授权

将用户重定向到袋袋授权页面：

GET https://api.profy.cn/oauth/authorize
  ?client_id={your_app_uuid}
  &redirect_uri={your_redirect_uri}
  &response_type=code
  &scope=events:write
  &state={random_state}

参数	必填	说明
`client_id`	✅	你的 App UUID
`redirect_uri`	✅	注册过的回调地址
`response_type`	✅	必须为 `code`
`scope`	否	请求的权限范围（空格分隔）
`state`	推荐	随机字符串，防 CSRF 攻击

用户会看到袋袋的授权页面，展示你的 App 名称和请求的权限。用户同意后，袋袋会将用户重定向回你的回调地址。

第三步：接收授权码

用户授权后，袋袋将用户重定向到你的 redirect_uri：

https://your-app.com/callback?code={authorization_code}&state={your_state}

授权码（Authorization Code）有效期为 5 分钟，且只能使用一次。请在收到后立即换取 Token。

第四步：换取 Token

使用授权码换取 Access Token 和 Refresh Token：

import httpx

async def exchange_token(code: str, redirect_uri: str):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.profy.cn/oauth/token",
            json={
                "grant_type": "authorization_code",
                "code": code,
                "redirect_uri": redirect_uri,
                "client_id": "your-app-uuid",
                "client_secret": "your-client-secret",
            },
        )
        return resp.json()

# 返回示例:
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIs...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "a1b2c3d4e5f6...",
#   "scope": "events:write"
# }

async function exchangeToken(code: string, redirectUri: string) {
  const resp = await fetch("https://api.profy.cn/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code,
      redirect_uri: redirectUri,
      client_id: "your-app-uuid",
      client_secret: "your-client-secret",
    }),
  });
  return resp.json();
}

curl -X POST https://api.profy.cn/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "your-auth-code",
    "redirect_uri": "https://your-app.com/callback",
    "client_id": "your-app-uuid",
    "client_secret": "your-client-secret"
  }'

Token 端点也支持 application/x-www-form-urlencoded 格式。

Token 生命周期

Token 类型	有效期	用途
Access Token	1 小时	API 调用认证
Refresh Token	90 天	换取新的 Token 对

Access Token

JWT 格式（RS256 签名）
包含 sub（用户 ID）、aud（App UUID）、scope（权限范围）
过期后使用 Refresh Token 获取新 Token

Refresh Token

不透明字符串格式
旋转机制：每次使用后旧 Token 失效，返回新的 Refresh Token
使用过的 Refresh Token 不能再次使用

第五步：刷新 Token

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

async def refresh_tokens(refresh_token: str):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.profy.cn/oauth/token",
            json={
                "grant_type": "refresh_token",
                "refresh_token": refresh_token,
                "client_id": "your-app-uuid",
                "client_secret": "your-client-secret",
            },
        )
        data = resp.json()
        # 重要：保存新的 refresh_token，旧的已失效
        new_access_token = data["access_token"]
        new_refresh_token = data["refresh_token"]
        return new_access_token, new_refresh_token

async function refreshTokens(refreshToken: string) {
  const resp = await fetch("https://api.profy.cn/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "refresh_token",
      refresh_token: refreshToken,
      client_id: "your-app-uuid",
      client_secret: "your-client-secret",
    }),
  });
  const data = await resp.json();
  // 重要：保存新的 refresh_token，旧的已失效
  return { accessToken: data.access_token, refreshToken: data.refresh_token };
}

curl -X POST https://api.profy.cn/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "your-refresh-token",
    "client_id": "your-app-uuid",
    "client_secret": "your-client-secret"
  }'

Refresh Token 使用旋转机制。每次刷新后，你必须保存新的 Refresh Token。旧的 Refresh Token 在使用后立即失效。

吊销 Token

当用户注销或你需要撤回访问时，调用吊销端点：

curl -X POST https://api.profy.cn/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-refresh-token",
    "client_id": "your-app-uuid",
    "client_secret": "your-client-secret"
  }'

吊销端点遵循 RFC 7009 规范——即使 Token 已失效，也会返回 200 OK。

可用 Scopes

Scope	说明
`events:write`	允许调用 `/v1/agents/run`、`/v1/chat/completions`、`/v1/events`、`/v1/models`

安全最佳实践

使用 state 参数防止 CSRF

在发起授权请求时生成随机 state 值，回调时验证 state 是否匹配。

安全存储 Token

服务端：使用加密存储（数据库加密列、密钥管理服务）
客户端：使用 httpOnly cookie 或安全存储
不要在 URL、日志或前端 localStorage 中存放 Refresh Token

严格匹配 Redirect URI

袋袋会严格校验 redirect_uri 是否在注册列表中。请确保注册的 URI 包含完整路径，避免开放重定向漏洞。

安全存储 Client Secret

Client Secret 应仅在服务端使用，不要暴露在前端代码中。使用环境变量或密钥管理服务存储。

错误处理

错误	HTTP 状态码	说明
`invalid_client`	401	Client ID 不存在或 Client Secret 错误
`invalid_grant`	400	授权码过期/无效，或 Refresh Token 已使用/过期
`invalid_request`	400	缺少必填参数或 redirect_uri 未注册
`unsupported_grant_type`	400	grant_type 不是 `authorization_code` 或 `refresh_token`
`unsupported_response_type`	400	response_type 不是 `code`

概览

Platform API

认证与密钥

集成

SDK

Cookbook

参考

OAuth 集成

流程概览

第一步：注册 App

第二步：引导用户授权

第三步：接收授权码

第四步：换取 Token

Token 生命周期

Access Token

Refresh Token

第五步：刷新 Token

吊销 Token

可用 Scopes

安全最佳实践

错误处理

下一步

Events API

App 开发指南

​流程概览

​第一步：注册 App

​第二步：引导用户授权

​第三步：接收授权码

​第四步：换取 Token

​Token 生命周期

​Access Token

​Refresh Token

​第五步：刷新 Token

​吊销 Token

​可用 Scopes

​安全最佳实践

​错误处理

​下一步

Events API

App 开发指南

流程概览

第一步：注册 App

第二步：引导用户授权

第三步：接收授权码

第四步：换取 Token

Token 生命周期

Access Token

Refresh Token

第五步：刷新 Token

吊销 Token

可用 Scopes

安全最佳实践

错误处理

下一步