# Internal API Key 使用指南

Internal API Key 是为 Clinic 内部用户（`internal=true`）设计的认证机制，允许内部用户通过 API Key 访问所有 Clinic API。
FeishuDocs: https://pingcap.feishu.cn/wiki/BAsSwt9Cti8A93kF9o1cjdzynkb

## 前置条件

- 你必须是一个 **内部用户**（`internal=true`）
- 登录 [clinic.pingcap.com](https://clinic.pingcap.com)，在 **User Profile** 下创建 Access Key


> **重要**: `key` 字段只在创建时返回一次，请妥善保存！

## 使用 API Key 进行认证

创建 API Key 后，可以使用以下两种方式进行 API 认证：

### 方式一：Bearer Token（推荐）

```bash
curl -H "Authorization: Bearer <your-api-key>" \
  https://clinic.example.com/clinic/api/v1/orgs
```

### 方式二：Basic Auth

```bash
curl -u "api_key:<your-api-key>" \
  https://clinic.example.com/clinic/api/v1/orgs
```

## 权限说明

使用 Internal API Key 的内部用户可以访问**所有** Clinic API，不受 URI 白名单限制。

这与普通用户的 API Key 不同，普通用户的 API Key 只能访问以下端点：
- `/clinic/api/v1/diag/precreate`
- `/clinic/api/v1/diag/upload`
- `/clinic/api/v1/diag/flush`

## 安全建议

1. **妥善保管**: API Key 创建后只显示一次，请立即保存到安全的地方
2. **设置过期时间**: 建议为临时使用的 Key 设置过期时间
3. **定期轮换**: 定期删除旧的 Key 并创建新的
4. **最小权限**: 如果只需要上传诊断数据，使用普通的 Upload Key 而非 Internal Key

## 示例：完整流程

1. 登录 [clinic.pingcap.com](https://clinic.pingcap.com)
2. 进入 **User Profile** 页面
3. 在 Access Key 区域创建新的 Key，复制并保存
4. 使用 API Key 访问 API：

```bash
# 使用 API Key 访问 API
curl -H "Authorization: Bearer <your-api-key>" \
  "https://clinic.pingcap.com/clinic/api/v1/orgs"
```