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

# API Key 轮换

> 零停机轮换 ARouter API Key 的最佳实践。通过定期更换凭证保障应用安全。

定期轮换 API Key 可以降低密钥泄露的影响范围，并满足许多安全合规要求。ARouter 的密钥管理 API 支持零停机轮换。

## 轮换策略

最安全的轮换模式是**先创建后删除**：

1. 创建一个与旧密钥具有相同权限的新密钥
2. 将新密钥部署到您的应用程序
3. 验证新密钥是否正常工作
4. 删除旧密钥

这样可以确保零停机——在确认新密钥正常工作之前，流量继续使用旧密钥。

***

## 第一步：创建新密钥

使用[密钥管理 API](/zh/api-reference/keys/create-key) 创建替换密钥：

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.arouter.ai/v1/keys \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "production-v2",
        "allowed_providers": ["openai", "anthropic", "google"],
        "spending_limit": 500.00
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        "https://api.arouter.ai/v1/keys",
        headers={"Authorization": "Bearer lr_live_xxxx"},
        json={
            "name": "production-v2",
            "allowed_providers": ["openai", "anthropic", "google"],
            "spending_limit": 500.00,
        },
    )
    new_key = response.json()["key"]
    print(f"New key created: {new_key[:8]}...")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await fetch("https://api.arouter.ai/v1/keys", {
      method: "POST",
      headers: {
        Authorization: "Bearer lr_live_xxxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "production-v2",
        allowed_providers: ["openai", "anthropic", "google"],
        spending_limit: 500.0,
      }),
    });

    const { key } = await response.json();
    console.log(`New key: ${key.substring(0, 8)}...`);
    ```
  </Tab>
</Tabs>

**请立即保存返回的密钥值** — ARouter 仅在创建时返回完整密钥一次。

***

## 第二步：更新您的应用程序

在部署环境中更新 `AROUTER_API_KEY` 环境变量（或对应的 Secret）：

```bash theme={null}
# 使用 .env 文件示例
AROUTER_API_KEY=lr_live_new_key_here

# 更新 Kubernetes secret 示例
kubectl create secret generic arouter-credentials \
  --from-literal=api-key=lr_live_new_key_here \
  --dry-run=client -o yaml | kubectl apply -f -
```

重新部署或重启应用程序以使新密钥生效。

***

## 第三步：验证新密钥

在删除旧密钥之前，确认新密钥正常工作：

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/models \
      -H "Authorization: Bearer lr_live_new_key_here"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    # 使用新密钥测试
    client = OpenAI(
        base_url="https://api.arouter.ai/v1",
        api_key="lr_live_new_key_here",
    )

    response = client.chat.completions.create(
        model="openai/gpt-5.4",
        messages=[{"role": "user", "content": "ping"}],
        max_tokens=5,
    )
    print("New key verified:", response.choices[0].message.content)
    ```
  </Tab>
</Tabs>

检查 [ARouter 控制台](https://arouter.ai/keys)，确认请求已出现在新密钥下。

***

## 第四步：删除旧密钥

确认新密钥正常工作后，使用旧密钥 ID 将其删除：

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X DELETE https://api.arouter.ai/v1/keys/key_oldid \
      -H "Authorization: Bearer lr_live_new_key_here"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    requests.delete(
        "https://api.arouter.ai/v1/keys/key_oldid",
        headers={"Authorization": "Bearer lr_live_new_key_here"},
    )
    print("Old key deleted")
    ```
  </Tab>
</Tabs>

***

## 自动轮换

对于高安全性环境，可以使用 CI/CD 系统或密钥管理器按计划自动轮换：

### GitHub Actions 示例

```yaml theme={null}
name: Rotate ARouter Key

on:
  schedule:
    - cron: '0 0 1 * *'  # 每月执行

jobs:
  rotate:
    runs-on: ubuntu-latest
    steps:
      - name: Create new key
        id: create
        run: |
          NEW_KEY=$(curl -s -X POST https://api.arouter.ai/v1/keys \
            -H "Authorization: Bearer ${{ secrets.AROUTER_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"name": "production-auto-rotated"}' \
            | jq -r .key)
          echo "new_key=$NEW_KEY" >> $GITHUB_OUTPUT

      - name: Update secret
        uses: gliech/create-github-secret-action@v1
        with:
          name: AROUTER_API_KEY
          value: ${{ steps.create.outputs.new_key }}
          token: ${{ secrets.GH_TOKEN }}
```

***

## 列出活跃密钥

列出所有活跃密钥以审计当前使用情况：

```bash theme={null}
curl https://api.arouter.ai/v1/keys \
  -H "Authorization: Bearer lr_live_xxxx"
```

响应：

```json theme={null}
{
  "data": [
    {
      "id": "key_abc123",
      "name": "production-v2",
      "created_at": "2025-01-15T10:00:00Z",
      "last_used_at": "2025-04-01T08:30:00Z",
      "spending_limit": 500.00
    },
    {
      "id": "key_def456",
      "name": "staging",
      "created_at": "2025-03-01T09:00:00Z",
      "last_used_at": "2025-04-01T07:15:00Z",
      "spending_limit": 50.00
    }
  ]
}
```

***

## 最佳实践

* **定期轮换** — 对大多数应用程序而言，每月轮换是一个良好的基准
* **疑似泄露后立即轮换** — 不要等到下次计划轮换
* **使用描述性名称** — 在密钥名称中包含版本或日期（如 `production-2025-04`、`production-v3`）
* **设置消费限额** — 始终为生产密钥配置 `spending_limit` 以控制风险敞口
* **不同环境使用独立密钥** — 生产环境与预发布环境绝不共用同一密钥
* **定期审计** — 每月检查密钥列表，删除不再使用的密钥
* **将密钥存储在密钥管理器中** — 使用 AWS Secrets Manager、HashiCorp Vault 或同类工具，而非版本控制中的 `.env` 文件

完整密钥管理指南请参阅[密钥管理](/zh/guides/key-management)，完整 API 参考请参阅[密钥管理 API](/zh/api-reference/keys/create-key)。