Agent API Key

Agent API Key 是 AI Agent 调用 Open Connector 的主要认证机制。每个 Key 作用范围限定于某个项目，并在其元数据中携带该项目的 projectId 和 orgId。在每次请求中，通过 x-api-key 头传递此 Key。

Key 的权限范围

持有一个 API Key，您可以：

访问该 Key 所属项目下的所有已连接账户
为该项目内的新用户发起 OAuth 流程
代表该项目下任意已连接账户执行工具调用
在每条审计日志中自动归属到对应的项目和组织

一个 Key 不能访问同组织内其他项目的数据，也不能调用需要登录会话的 Console API 来执行管理或账单操作。

创建 API Key

打开 app.openconnector.dev，选择项目。
打开侧栏项目分组中的 API Keys。
点击 Create，填写易识别名称（如 support-agent-prod）并确认。
立即把明文 Key 保存到密钥管理服务。

明文 key 只会返回一次；之后的列表只显示前缀和状态等非机密元数据。需要使用 Session 认证进行自动化时，请查看实时 Console OpenAPI 文档，并使用 /api/v1/console 下公开的 API 路径。

Key 元数据结构

每个 API Key 都嵌入了在每次请求时进行验证的范围化元数据：

Prop

Type

在请求中使用 Key

将 Key 作为 x-api-key 请求头传递：

curl -X GET "https://api.openconnector.dev/composio/api/v3.1/connected_accounts" \
  -H "x-api-key: oc_abc123xyz..."

在 Agent 代码中使用：

import { createClient } from "@open-connector/sdk";

const oc = createClient({
  apiKey: process.env.OPEN_CONNECTOR_API_KEY!,
  baseUrl: "https://api.openconnector.dev",
});

import Composio from "@composio/client";

const composio = new Composio({
  apiKey: process.env.OPEN_CONNECTOR_API_KEY,
  baseURL: "https://api.openconnector.dev/composio",
});

安全最佳实践

请将 Agent API Key 视同密码处理。如果 Key 泄露，持有该 Key 的任何人都可以代表该项目下所有已连接账户执行工具调用。

将 Key 存储在密钥管理服务中（AWS Secrets Manager、Doppler、Vault 或平台原生方案）。切勿提交到版本控制系统，也不要将其嵌入客户端代码。
每个环境使用独立的 Key。 为开发、测试和生产环境分别使用不同的 Key，这样一个环境的泄露不会影响其他环境。
每个 Agent 使用独立的 Key。 如果您运行多个 Agent（例如研究 Agent 和写作 Agent），分别为它们创建 Key，便于独立轮换和归因追踪。
怀疑泄露时立即轮换。 如果您认为某个 Key 可能已经泄露，立即在控制台撤销它并创建新 Key。已有的连接不受影响。
监控审计日志。 每次工具调用都会写入审计日志，并附带 Key 的 projectId。活动量的异常增加可能意味着 Key 被滥用。

撤销 Key

在控制台中打开 API Keys，通过目标 Key 的操作菜单选择 Revoke。Key 会立即失效。为避免中断，请先发放替换 Key 再撤销旧 Key。