API 参考

Open Connector 有两个 API 平面。请按调用者身份选择：Agent 使用项目 API Key；控制台使用已登录用户的会话。

实时 API 文档

文档	URL	认证方式
Open Connector Scalar UI	api.openconnector.dev/api/v1/	受保护操作使用项目 API Key
Open Connector API	api.openconnector.dev/api/v1/spec.json	文档公开
Console Scalar UI	api.openconnector.dev/api/v1/console	受保护操作使用 Better Auth 会话

服务端从处理请求的同一份运行时 API Contract 生成这些文档。不要复制静态端点清单；部署版本的精确 Schema 以这里为准。

Agent 平面

已有 Composio 集成请使用兼容层：

https://api.openconnector.dev/composio/api/v3.1/

每次 Broker 请求都使用项目 API Key：

curl "https://api.openconnector.dev/composio/api/v3.1/toolkits?limit=20" \
  -H "x-api-key: $OPEN_CONNECTOR_API_KEY"

兼容层包含连接器发现、Auth Config、已连接账户、工具调用等已部署的 Composio 风格路由。某个可选子系统没有配置时，路由会返回明确错误，而不是伪造空成功。

常见 Agent 流程

为连接器创建 Auth Config。
为用户创建已连接账户（或托管连接链接）。
针对该连接调用工具。

curl -X POST "https://api.openconnector.dev/composio/api/v3.1/tools/execute/GITHUB_CREATE_AN_ISSUE" \
  -H "x-api-key: $OPEN_CONNECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "conn_...",
    "arguments": {"owner": "acme", "repo": "support", "title": "Brokered issue"}
  }'

连接生命周期和错误处理请参阅已连接账户与调用工具。

控制台平面

公开的 Console API 挂载在 /api/v1/console，使用 Better Auth Session Cookie，只面向管理控制台或可信的管理工具，不面向 AI Agent。

项目 API Key、组织、项目、账单和设置的管理都属于这个会话认证平面。需要程序化调用时，请先检查 Console Scalar UI，确保路由和请求体与当前部署的 contract 一致。

认证边界

调用者	凭证	范围
Agent / 后端服务	`x-api-key: oc_...`	一个项目及其连接
控制台用户	Better Auth 会话 Cookie	用户拥有权限的组织
OAuth 回调	Broker 创建的签名 state	仅正在进行的连接

不要把项目 API Key 交给不受信任的浏览器，也不要让 Agent 代码使用控制台 session cookie。

自托管实例

将 https://api.openconnector.dev 替换为您的服务公开 origin，路由保持不变：

https://connector.example.com/api/v1/spec.json
https://connector.example.com/composio/api/v3.1/

OAuth 回调 base 也必须可从公网访问；请参阅环境变量和部署到 AWS。