# 身份验证

每个 API 请求都必须携带您的 API 密钥，以便 <span data-t="appName">Your AI Connector</span> 识别您的身份以及需要操作的账户。您可以通过四种不同的方式发送密钥——所有方式均适用于支持 API 密钥身份验证的每个端点，因此请选择最适合您设置的一种。

API 访问是一项付费功能。如果您的套餐不包含此功能，即使密钥本身有效，请求也会被拒绝并返回 `403`——请参阅下方的 [付费功能门槛](#the-paid-feature-gate)。要生成密钥，请参阅 [API 访问](../integrations/api-access.md)。

> **仅限 HTTPS。** 所有请求都必须使用安全连接。普通的 HTTP 请求会在身份验证运行之前被拒绝。

---

## 四种方法概览

| 方法 | 载体 | 使用场景 |
|---|---|---|
| 查询参数 | `?apiKey=YOUR_API_KEY` | 快速测试和浏览器 URL |
| 请求头 | `X-API-Key: YOUR_API_KEY` | 生产环境集成 |
| Bearer 请求头 | `Authorization: Bearer YOUR_API_KEY` | 生产环境集成 |
| Firebase ID 令牌 | `Authorization: Bearer <ID token>` | 仅限第一方应用会话 |

当存在多个载体时，查询参数优先级最高，其次是 `X-API-Key` 请求头，最后是 Bearer 令牌。实际上，您通常只会发送其中一种。

---

## 1. 查询参数 — `?apiKey=`

将您的密钥添加到网址末尾。这是最简单的形式，且始终有效，因此非常适合快速测试、脚本编写以及任何旧版工具。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()
```

> **注意：** 网址会出现在浏览器历史记录、服务器访问日志和代理日志中。对于快速测试以外的任何用途，请优先使用下方的请求头方法，以免您的密钥以明文形式写入磁盘。

---

## 2. `X-API-Key` 请求头

在专用请求头中发送密钥。这可以避免密钥出现在 URL 中，是生产环境的推荐选择。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

---

## 3. `Authorization: Bearer` 请求头

您也可以将密钥作为标准的 Bearer 令牌传递。当您的 HTTP 客户端或框架已经内置了对 `Authorization` 请求头的支持时，这种方法非常方便。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()
```

API 会自动区分您的 API 密钥和登录令牌，因此该方法的工作方式与 `X-API-Key` 完全相同。

---

## 4. Firebase ID 令牌（仅限第一方）

如果您正在构建一个通过 <span data-t="appName">Your AI Connector</span> 自有登录方式让用户登录的第一方应用，您可以将该已登录用户的 Firebase ID 令牌作为持有者令牌（bearer token）传递，而不是使用 API 密钥：

```
Authorization: Bearer <Firebase ID token>
```

该令牌会在每次请求时进行验证，并映射到已登录的账户。**此方法仅适用于第一方应用会话**——您无法从外部集成中生成这些令牌，并且如果不通过正常的应用登录流程，也无法获取此类令牌。对于服务器到服务器的集成以及第三方集成，请使用 API 密钥（方法 1–3）。

---

## 何时使用哪种方式

- **快速测试和一次性脚本** → 查询参数 (`?apiKey=`)。输入最快，可在浏览器中使用。
- **生产环境集成和服务器到服务器调用** → `X-API-Key` 或 `Authorization: Bearer YOUR_API_KEY`。可避免将密钥暴露在 URL 和日志中。
- **拥有已登录 <span data-t="appName">Your AI Connector</span> 用户的第一方应用** → `Authorization: Bearer <Firebase ID token>`。

---

## 密钥范围

您的账户拥有一个**主 API 密钥** — 即位于 **设置 → 集成 → API 密钥** 下的那个。它拥有账户所有功能的完全访问权限。

您还可以创建额外的**范围限定密钥**：即仅能访问您所选 API 部分的命名密钥，例如仅限于“分析”功能的只读密钥，用于报表仪表板。范围限定密钥的发送方式与主密钥完全相同（上述方法 1–3 中的任意一种），但在每次请求时都会根据其自身的权限进行检查：

- **在其允许范围之外的操作将被拒绝。** 使用只读密钥进行写入操作，或调用该密钥未被授权的部分，将返回 `403` — `key_read_only` 或 `key_scope_denied`（位于 `error_code` 字段中）。此检查非常严格：任何未明确包含在密钥允许范围内的操作都会被拒绝，而不是被放行。因此，如果您看到其中一个 `403`，则说明该密钥不涵盖该端点。
- **它拥有独立的速率限制配额。** 范围限定密钥与您的主密钥分开计算，因此使用范围限定密钥的繁忙仪表板不会耗尽其他集成所依赖的配额。您可以在创建密钥时选择每分钟的预算。
- **它无法管理 API 密钥。** 只有账户所有者（登录状态或使用主密钥）才能列出、创建、编辑、轮换或撤销密钥。范围限定密钥永远无法创建权限更高的密钥。

请参阅 [API 密钥](api-keys.md) 以了解如何创建、编辑和撤销范围限定密钥。

---

## 付费功能限制

API 访问是一项付费功能。当您的套餐不包含此功能时，即使密钥有效，请求也会被拒绝，并返回 `403`：

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

If you see this, check your plan or contact [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}
```

---

## 确保密钥安全

- **像对待密码一样对待密钥。** 您的主密钥授予对您账户的完全访问权限。如果您需要将密钥提供给仅需部分权限的工具或人员，请改用范围限定密钥 — 请参阅 [密钥范围](#key-scopes)。
- **将其保留在服务器端。** 切勿将其嵌入浏览器 JavaScript、移动应用包或任何最终用户可读取的代码中。
- **将其存储在密钥管理器**或服务器端配置中，而不是源代码管理中。
- **如果发生泄露，请轮换密钥。** 从仪表板生成新密钥或调用 `POST https://api.youraiconnector.com/v1/api-keys/rotate` — 这会立即作废旧密钥。请参阅 [API 密钥](api-keys.md)。
- **始终使用 HTTPS**，以便密钥在传输过程中被加密。

---

## 后续步骤

- [入门指南](getting-started.md) — 您的首次请求和资源指南。
- [错误与分页](errors-and-pagination.md) — 处理失败情况并对结果进行分页。
- [API 密钥](api-keys.md) — 轮换、撤销和检查您的密钥使用情况。