API 密钥 API

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

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

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

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

https://api.youraiconnector.com/v1

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

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

获取当前密钥元数据

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

GET /api-keys/current

cURL

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

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.

响应

{
  "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

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

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

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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 浏览器中看到的相同部分名称编写 — `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

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

响应

{
  "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

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

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

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

{
  "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

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
    }
  }'

响应

{
  "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

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

响应

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

API 密钥 API 错误

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

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

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

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

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

后续步骤

身份验证 —— 验证请求的四种方式，以及如何强制执行密钥作用域。
错误与速率限制 —— 状态码和每分钟 300 次请求的限制。

API 密钥 API #

获取当前密钥元数据 #

获取速率限制使用情况 #

轮换密钥 #

撤销密钥 #

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

作用域密钥 #

列出作用域密钥 #

创建作用域密钥 #

更新作用域密钥 #

撤销作用域密钥 #

API 密钥 API 错误 #

后续步骤 #

API 密钥 API

获取当前密钥元数据

获取速率限制使用情况

轮换密钥

撤销密钥

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

作用域密钥

列出作用域密钥

创建作用域密钥

更新作用域密钥

撤销作用域密钥

API 密钥 API 错误

后续步骤