认证 - Profy

袋袋平台 API 支持两种认证方式，分别适用于不同的集成场景。所有认证信息都通过 Authorization 请求头传递。

API Key 认证

API Key 是最简单的认证方式，适用于服务端到服务端的直接调用。

使用方式

在请求头中添加 Authorization: Bearer sk-pro-xxxx：

from profy import Profy

client = Profy(api_key="sk-pro-your-key-here")

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key-here" });

curl -H "Authorization: Bearer sk-pro-your-key-here" \
     https://api.profy.cn/v1/models

特征

属性	说明
前缀	`sk-pro-`
积分扣除	从开发者自己的账户扣除
适用端点	`/v1/agents/run`、`/v1/chat/completions`、`/v1/models`
不适用	`/v1/events`（需要 OAuth）
存储方式	SHA-256 哈希存储，仅创建时展示原文

适用场景

后端服务调用 AI 能力
自动化脚本和定时任务
内部工具和管理系统
开发测试阶段

安全最佳实践

API Key 是你账户的凭证，泄露可能导致积分被消耗。请遵循以下安全实践：

不要在前端代码中使用 API Key——浏览器端的代码可被用户查看
使用环境变量存储 Key，不要硬编码在源码中
设置过期时间——在 Platform Console 创建 Key 时选择过期期限
按需分配权限范围（scope）——不要使用全量权限
定期轮换——定期创建新 Key 并吊销旧 Key

# 推荐：使用环境变量
export PROFY_API_KEY="sk-pro-your-key-here"

import os
from profy import Profy

client = Profy(api_key=os.environ["PROFY_API_KEY"])

import { Profy } from "@profy-ai/sdk";

const client = new Profy({
  apiKey: process.env.PROFY_API_KEY!,
});

OAuth Bearer 认证

OAuth 认证适用于代表用户操作的 App 场景。通过标准 OAuth 2.0 Authorization Code 流程获取 Access Token。

使用方式

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
     https://api.profy.cn/v1/chat/completions

特征

属性	说明
Token 格式	JWT（RS256 签名）
积分扣除	从授权用户的账户扣除
适用端点	所有 `/v1/*` 端点
Access Token 有效期	1 小时
Refresh Token 有效期	90 天（旋转机制）

适用场景

App 代表用户调用 AI 模型
需要用户授权的第三方应用
按用户计费的 SaaS 产品
自定义计费事件上报（/v1/events 仅支持 OAuth）

OAuth 流程概览

用户 → 你的 App → 袋袋授权页 → 用户同意 → 授权码 → 换取 Token

详细的 OAuth 集成指南请参阅 OAuth 集成。

两种方式对比

维度	API Key	OAuth Bearer
复杂度	简单（一个 Key 即可）	较复杂（需要完整 OAuth 流程）
积分来源	开发者账户	授权用户账户
适用场景	服务端直接调用	代表用户操作的 App
Events API	❌ 不支持	✅ 支持
Token 管理	手动创建和吊销	自动过期和刷新
前端可用	❌ 不安全	✅ 可用（短期 Token）

如何选择

确定计费主体

如果积分应从你自己的账户扣除 → API Key如果积分应从用户的账户扣除 → OAuth

确定调用方式

如果是后端服务直接调用 → API Key如果是App 代表用户操作 → OAuth

确定功能需求

如果需要使用 Events API 上报自定义计费事件 → OAuth其他场景两者均可

认证错误

当认证失败时，API 会返回以下错误：

HTTP 状态码	场景	说明
`401`	API Key 无效或已过期	检查 Key 是否正确、是否已吊销或过期
`401`	Access Token 过期	使用 Refresh Token 获取新的 Access Token
`401`	Refresh Token 无效	需要用户重新授权
`403`	权限不足	API Key 的 scope 不包含所请求的端点

错误响应示例：

{
  "error": {
    "message": "Unauthorized",
    "type": "auth_error"
  }
}

速率限制

API 调用受速率限制保护。限制按 API Key 或 OAuth Token 所属用户维度计算。当触发速率限制时，API 返回 429 Too Many Requests：

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}

在 Platform Console 的 Usage Stats 页面可以查看你的 API 调用量和速率使用情况。

概览

Platform API

认证与密钥

集成

SDK

Cookbook

参考

认证

API Key 认证

使用方式

特征

适用场景

安全最佳实践

OAuth Bearer 认证

使用方式

特征

适用场景

OAuth 流程概览

两种方式对比

如何选择

认证错误

速率限制

下一步

API Key 管理

OAuth 集成

​API Key 认证

​使用方式

​特征

​适用场景

​安全最佳实践

​OAuth Bearer 认证

​使用方式

​特征

​适用场景

​OAuth 流程概览

​两种方式对比

​如何选择

​认证错误

​速率限制

​下一步

API Key 管理

OAuth 集成

API Key 认证

使用方式

特征

适用场景

安全最佳实践

OAuth Bearer 认证

使用方式

特征

适用场景

OAuth 流程概览

两种方式对比

如何选择

认证错误

速率限制

下一步