# API 密钥 API

这些端点允许您通过代码管理账户的 API 密钥。它们仅对调用账户自身的密钥进行操作。

密钥有两种类型，它们位于不同的路径下：

- **主密钥** — 位于 **设置 → 集成 → API 密钥** 下的单个完全访问权限密钥。您可以查看其掩码预览、检查速率限制使用情况、轮换或撤销它。这些对应于下方的 `/api-keys/current`、`/api-keys/rotate` 和 `/api-keys/usage` 端点。
- **作用域密钥** — 您为特定任务创建的额外命名密钥，每个密钥仅限于您选择的 API 部分。这些对应于 [作用域密钥](#scoped-keys) 下的 `/api-keys` 和 `/api-keys/{id}` 端点。创建作用域密钥不会更改您的主密钥；现有的集成将不受影响。

以下所有路径均相对于 API 基础 URL：

```
https://api.youraiconnector.com/v1
```

每个请求都必须经过身份验证。请参阅 [身份验证](authentication.md) 以了解四种支持的方法。此处的示例使用 `X-API-Key` 标头（以及一种用于 cURL 的查询参数形式）。

> **请先阅读此内容。** 轮换或撤销密钥会**立即**生效。一旦调用成功，旧密钥将立即停止工作——所有仍在使用该密钥的集成都将开始收到 `401` 错误。请做好计划：在维护窗口期间进行轮换，并立即更新所有集成。

---

## 获取当前密钥元数据

返回您的活动密钥：当存在可检索的副本时，显示 `api_key` 中的完整密钥；否则显示掩码预览（前 4 位和后 4 位字符），并在可用时显示其创建日期。`api_key` 对于在保留可检索副本之前创建的密钥为 `null` —— 轮换一次后，新密钥即可在以后再次显示。

`GET /api-keys/current`

**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

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

**响应**

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}
```

如果账户没有 API 密钥，响应将为 `404` 并包含 `{ "success": false, "error": "No API key found for this account" }`。

---

## 获取速率限制使用情况

返回当前窗口的速率限制使用情况：每个窗口的请求限制、目前已计数的请求数、剩余请求数以及窗口重置时间。使用此信息构建客户端限流，以便您的集成在达到 `429` 响应之前进行退避。

`GET /api-keys/usage`

**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

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

**响应**

```json
{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}
```

如果当前窗口中尚未记录任何请求，则使用量报告为零，且响应包含一个解释原因的 `note` 字段。

---

## 轮换密钥

生成一个新的 API 密钥并同时使上一个密钥失效。如果您怀疑密钥已泄露，或者作为常规凭据轮换策略的一部分，请使用此功能。

`POST /api-keys/rotate`

> **新密钥仅显示一次。** 它会在本次响应中返回，之后无法再次完整获取——请在收到它的那一刻将其安全存储。旧密钥会在本次调用成功后立即失效，因此请务必更新所有使用该密钥的集成。
**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.
```

**响应**

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}
```

---

## 撤销密钥

永久删除您账户的 API 密钥。撤销操作是即时的：后续所有使用该已撤销密钥的请求（包括 Make、Zapier 或自定义脚本等集成）都将被拒绝，并返回 `401`。若之后需要恢复 API 访问权限，请在登录应用后从账户设置中生成新密钥。
`DELETE /api-keys/current`

> **此操作无法撤销。** 与轮换不同，撤销操作不会为您提供替换密钥。仅在您打算停止 API 访问时才执行撤销（例如，密钥泄露且无法立即替换时）。
**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

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

**响应**

```json
{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}
```

如果账户没有可撤销的密钥，响应将返回 `404`。
---

## 作用域密钥

作用域密钥是您为特定任务创建的额外 API 密钥，仅具备该任务所需的访问权限。典型场景：您希望将客户仪表板、报告工具或内部脚本指向您的账户，而无需提供一个可以发送消息、更改 AI 代理或购买电话号码的密钥。

限制随密钥本身生效，因此持有该密钥的人只能执行您在创建时允许的操作。

**您可以限制的内容**

| 字段 | 含义 |
|---|---|
| `read_only` | `true`（默认值）表示仅允许读取请求。任何创建、更新或删除请求都将被拒绝。 |
| `tags` | 密钥可以使用的 API 部分列表，使用您在本文档和 [API 浏览器](reference.md) 中看到的相同部分名称编写 — `Analytics`、`Campaigns`、`Contacts`、`Messages`、`Appointments` 等。列表为空表示所有部分。 |
| `sub_account_ids` | 密钥可以操作的托管账户。为空表示仅限您自己的账户；`["*"]` 表示您可以实际管理的任何账户。所有权仍会在每个请求中进行检查。 |
| `rate_limit_per_min` | 此密钥每分钟的请求数，在其自己的配额中计算，因此它不会耗尽您其他集成的配额。默认为 `60`，且不能设置为高于 `300` 的值。 |

您还可以为密钥设置 `expires_at` 日期（ISO 8601 格式，且必须是未来日期）。在该时间点之后，密钥将自动停止工作。如果不设置，密钥将永远不会过期，除非您撤销它。

> **拒绝默认关闭。** 如果请求超出了密钥允许的范围，它将被拒绝而不是被放行：使用只读密钥进行写入操作会返回带有 `error_code: "key_read_only"` 的 `403`，而超出密钥允许部分的任何操作都会返回带有 `error_code: "key_scope_denied"` 的 `403`。如果作用域密钥收到意外的 `403`，则说明您调用的端点不在其作用域内 — 请扩大密钥权限或使用您的主密钥。

> **仅账户所有者可以管理密钥。** 这四个端点需要您的主密钥或应用中的所有者会话。作用域密钥永远无法列出、创建、编辑或撤销密钥（包括其自身）— 因此受限密钥永远无法用于创建权限更大的密钥。尝试执行此操作将返回带有 `error_code: "key_scope_denied"` 的 `403`。出于同样的原因，`API Keys` 不是您可以授予的部分：请求它将返回带有 `error_code: "invalid_scopes"` 的 `400`。

### 列出作用域密钥

返回账户的作用域密钥，按最新顺序排列（最多 200 个），包括已撤销的密钥，以便您查看撤销的内容和时间。仅返回掩码预览 — 作用域密钥的值仅在创建时显示一次，之后无法检索。

`GET /api-keys`

**cURL**

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

**响应**

```json
{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}
```

### 创建作用域密钥

创建一个新的作用域密钥并**仅一次**返回其值。

`POST /api-keys`

> **密钥仅显示一次。** 它仅出现在此响应中，绝不会再出现——事后无法再次查询。请在收到密钥时立即存储。如果丢失，请撤销并创建一个新的。

**请求体字段** — 均为可选：

| 字段 | 类型 | 说明 |
|---|---|---|
| `label` | string | 您为密钥起的名称，显示在列表和“设置”中。 |
| `scopes` | object | 上表中的四个字段。如果省略整个对象，将获得安全默认值：只读、限制为 `Analytics`、仅限您自己的账户、每分钟 60 次请求。 |
| `expires_at` | ISO 8601 日期 | 可选的过期时间，必须是未来的时间。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.
```

**响应** — `201 Created`

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}
```

在基于此构建时，有几点细节值得注意：

- **省略 `scopes` 与发送空的 `tags` 列表不同。** 完全省略 `scopes` 将获得安全默认值（只读，仅限 `Analytics`）。故意发送 `"tags": []`，则密钥可以使用所有部分——这被视为对无限制密钥的明确请求。
- **`read_only` 保持为 `true`，除非您显式发送 `false`。** 拼写错误或缺失标志绝不会意外生成具有写入权限的密钥。

### 更新作用域密钥

更改密钥的标签、作用域和/或过期时间。发送这三者的任意组合；如果不发送任何内容，将返回 `400`。

`PATCH /api-keys/{id}`

`{id}` 是列表中密钥的 `id`（即 `key_...` 值），绝不是密钥本身。

> **作用域是替换而非合并。** 您发送的任何内容都将成为密钥的完整权限集。这是刻意设计的：缩小密钥权限绝不会静默地保留旧的、更广泛的访问权限。请始终发送您想要的完整 `scopes` 对象，而不仅仅是您要更改的字段。

密钥的值永远不会改变。作用域密钥没有原地轮换功能——要轮换密钥，请创建一个新密钥并撤销旧密钥，这样凭据的访问权限就不会在仍持有该凭据的集成中发生变化。

**cURL**

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'
```

**响应**

```json
{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}
```

如果您的账户中没有该 ID 的密钥，响应将为 `404`。

### 撤销作用域密钥

撤销操作是即时的：使用该密钥的下一个请求会立即被拒绝，并返回 `401`。您的主密钥和其他所有作用域密钥均不受影响。

`DELETE /api-keys/{id}`

该密钥会保留在您的列表中并标记为 `"revoked": true`，因此您可以记录曾经存在过哪些密钥以及它们可以访问的范围。撤销一个已撤销的密钥会显示成功，但不会有任何改变。

**cURL**

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

**响应**

```json
{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}
```

---

## API 密钥 API 错误

API 密钥端点返回标准的错误封装：

```json
{
  "success": false,
  "error": "No API key found for this account"
}
```

在 API 密钥端点上，缺少或无效的密钥会返回 `401`，而账户中没有存档密钥时会返回 `404`。每个端点都可能返回的共享代码 — `400`、`403`（您的套餐不包含 API 访问权限）、`429`（速率限制）和 `500` — 及其重试指南列在[错误与分页](errors-and-pagination.md)中。

作用域密钥端点在 `error_code` 字段中添加了一些命名代码，以便您区分不同情况：

| `error_code` | 状态 | 发生了什么 |
|---|---|---|
| `key_read_only` | `403` | 只读密钥尝试执行写入操作。 |
| `key_scope_denied` | `403` | 该密钥不允许用于该端点或该托管账户——或者作用域密钥尝试管理 API 密钥，这是绝对不允许的。 |
| `invalid_scopes` | `400` | 请求的作用域包含了 `API Keys` 部分。密钥无法管理密钥。 |
| `404` | `404` | 您的账户中不存在该 ID 的密钥。 |

---

## 后续步骤

- [身份验证](authentication.md) —— 验证请求的四种方式，以及如何强制执行密钥作用域。
- [错误与速率限制](errors-and-pagination.md) —— 状态码和每分钟 300 次请求的限制。