> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# API Key

API Key 是一种用于在 CI/CD 流程或自动化脚本中调用 [Pushy API](https://update.reactnative.cn/api/openapi) 的认证方式。相比直接使用账号密码，API Key 更加安全且便于管理。

## 使用场景

- **持续集成/持续部署 (CI/CD)**：在 GitHub Actions、GitLab CI、Jenkins 等平台中自动发布热更新
- **自动化脚本**：编写脚本批量管理应用、版本或原生包
- **第三方工具集成**：将 Pushy 与其他开发工具集成

## 创建 API Key

1. 登录 [Pushy 管理后台](https://pushy-admin.reactnative.cn)
2. 在左侧菜单中点击「API Key」
3. 点击「创建 API Key」按钮
4. 填写 API Key 名称（如：CI/CD Pipeline）
5. 选择所需权限
6. 可选设置过期时间
7. 点击创建后，**立即复制并安全保存 API Key**

:::warning
API Key 只会在创建时显示一次，之后无法再次查看。请务必在创建后立即复制保存！
:::

## 权限说明

| 权限              | 说明                 |
| --------------- | ------------------ |
| **读取 (read)**   | 查看应用、版本、原生包信息      |
| **写入 (write)**  | 创建和更新应用、发布版本、上传原生包 |
| **删除 (delete)** | 删除应用、版本、原生包        |

:::info
创建 API Key 时至少需要选择一个权限。根据实际需求选择最小必要权限是最佳实践。
:::

## 使用 API Key 调用 API

在调用 Pushy API 时，将 API Key 添加到请求头中：

```bash
curl -X GET "https://update.reactnative.cn/api/app/list" \
  -H "x-api-token: YOUR_API_TOKEN"
```

:::info
请求头 `x-api-token` 与环境变量 `PUSHY_API_TOKEN` 是接口层面的名字，为兼容既有集成保持不变；页面与文档中统称 API Key，两者指的是同一样东西。
:::

### 在命令行工具中使用

如果使用 `react-native-update-cli` 命令行工具（需 v2.7.0+），可以通过环境变量设置 API Key：

```bash
export PUSHY_API_TOKEN=your_api_token_here
pushy bundle --platform android
```

### 在 CI/CD 中使用

以 GitHub Actions 为例：

```yaml
# .github/workflows/publish.yml
name: Publish Hot Update

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
          
      - name: Install dependencies
        run: npm install && npm i -g react-native-update-cli
        
      - name: Publish update
        env:
          PUSHY_API_TOKEN: ${{ secrets.PUSHY_API_TOKEN }}
        run: pushy bundle --platform android
```

:::tip
在 CI/CD 环境中，建议将 API Key 存储在密钥管理中（如 GitHub Secrets），而不是直接写入代码。
:::

## 管理 API Key

### 查看 API Key 列表

在「API Key」页面可以看到所有已创建的 API Key，包括：

- API Key 名称
- 权限
- 过期时间
- 最后使用时间
- 状态（正常/已过期/已撤销）

### 撤销 API Key

如果 API Key 泄露或不再需要，可以随时撤销：

1. 在 API Key 列表中找到目标 API Key
2. 点击「撤销」按钮
3. 确认撤销

:::warning
API Key 撤销后立即生效，使用该 API Key 的所有请求将被拒绝。请确保在撤销前更新相关的 CI/CD 配置。
:::

## 安全建议

1. **最小权限原则**：只授予 API Key 必要的权限
2. **设置过期时间**：为临时使用的 API Key 设置合理的过期时间
3. **定期轮换**：定期撤销旧 API Key 并创建新 API Key
4. **安全存储**：不要将 API Key 提交到代码仓库，使用环境变量或密钥管理工具
5. **监控使用**：定期检查 API Key 的最后使用时间，及时清理不再使用的 API Key

## 限制

- 每个用户最多可创建 **10 个** API Key
- 如需创建更多，请先撤销不再使用的 API Key