> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证

> 了解袋袋 API 的两种认证方式：API Key 和 OAuth Bearer

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

## API Key 认证

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

### 使用方式

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

<CodeGroup>
  ```python Python theme={null}
  from profy import Profy

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

  ```typescript TypeScript theme={null}
  import { Profy } from "@profy-ai/sdk";

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

  ```bash curl theme={null}
  curl -H "Authorization: Bearer sk-pro-your-key-here" \
       https://api.profy.cn/v1/models
  ```
</CodeGroup>

### 特征

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

### 适用场景

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

### 安全最佳实践

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

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

```bash theme={null}
# 推荐：使用环境变量
export PROFY_API_KEY="sk-pro-your-key-here"
```

<CodeGroup>
  ```python Python theme={null}
  import os
  from profy import Profy

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

  ```typescript TypeScript theme={null}
  import { Profy } from "@profy-ai/sdk";

  const client = new Profy({
    apiKey: process.env.PROFY_API_KEY!,
  });
  ```
</CodeGroup>

## OAuth Bearer 认证

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

### 使用方式

```bash theme={null}
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 集成](/zh/developers/oauth-integration)。

## 两种方式对比

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

### 如何选择

<Steps>
  <Step title="确定计费主体">
    如果积分应从**你自己的账户**扣除 → API Key

    如果积分应从**用户的账户**扣除 → OAuth
  </Step>

  <Step title="确定调用方式">
    如果是**后端服务**直接调用 → API Key

    如果是**App 代表用户**操作 → OAuth
  </Step>

  <Step title="确定功能需求">
    如果需要使用 **Events API** 上报自定义计费事件 → OAuth

    其他场景两者均可
  </Step>
</Steps>

## 认证错误

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

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

错误响应示例：

```json theme={null}
{
  "error": {
    "message": "Unauthorized",
    "type": "auth_error"
  }
}
```

## 速率限制

API 调用受速率限制保护。限制按 API Key 或 OAuth Token 所属用户维度计算。

当触发速率限制时，API 返回 `429 Too Many Requests`：

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}
```

<Tip>
  在 [Platform Console](https://platform.profy.cn) 的 Usage Stats 页面可以查看你的 API 调用量和速率使用情况。
</Tip>

## 下一步

<CardGroup cols={2}>
  <Card title="API Key 管理" icon="key" href="/zh/developers/api-key-management">
    创建、查看、吊销 API Key 的完整指南
  </Card>

  <Card title="OAuth 集成" icon="shield" href="/zh/developers/oauth-integration">
    完整的 OAuth 2.0 集成流程
  </Card>
</CardGroup>