连接账户

连接账户是某个用户对特定认证配置完成授权后的结果。它代表一次成功的授权流程的产物：用户已向您的 OAuth 应用授予了对其第三方账户的访问权限，Open Connector 已将所得凭证加密存储在保险库中。

每个连接账户都作用于某个项目，并绑定到一个您提供的用户标识符。Agent 在调用工具时通过 ID 引用连接账户 — Agent 始终看不到底层 Token。

OAuth 授权流程

发起连接

您的 Agent 或后端服务调用 POST /composio/api/v3.1/connected_accounts，传入 auth_config id（您注册的 OAuth 应用凭证）和 connection.user_id（您系统中标识该用户的唯一 ID）。Open Connector 返回一个 redirect_url。

重定向用户

将用户引导至 redirect_url。用户会先到达 Open Connector 的托管连接页面，再被带到第三方服务提供商的授权页面（例如 GitHub 的 OAuth 同意界面），在那里授予访问权限。

Open Connector 处理回调

服务提供商将用户重定向回 Open Connector 的回调端点。Open Connector 将授权码交换为 Access Token 和 Refresh Token，使用 AES-256-GCM 加密后存储到保险库中。连接状态变更为 ACTIVE。

使用连接

连接账户现在已就绪。在工具执行调用中传入其 ID — Open Connector 在服务端解密 Token，将其注入到出站请求的认证头中。

API 操作

创建连接（发起 OAuth）

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

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

const connection = await oc.initiate({
  slug: "github",
  authConfigId: "ac_01j9abc123",
  entityId: "user_from_your_app",
});

console.log(connection.redirectUrl);

import Composio from "@composio/client";

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

const connection = await composio.connectedAccounts.create({
  auth_config: { id: "ac_01j9abc123" },
  connection: {
    user_id: "来自您系统的用户ID",
    // callback_url 可选 — 省略时使用 Open Connector 的托管页面
    callback_url: "https://yourapp.com/oauth/callback",
  },
} as any);

// 将用户重定向到此 URL
console.log(connection.redirect_url);

curl -X POST "https://api.openconnector.dev/composio/api/v3.1/connected_accounts" \
  -H "x-api-key: oc_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "auth_config": { "id": "ac_01j9abc123" },
    "connection": {
      "user_id": "来自您系统的用户ID",
      "callback_url": "https://yourapp.com/oauth/callback"
    }
  }'

响应示例（201）：

{
  "id": "conn_01j9xyz789",
  "connectionData": { "authScheme": "OAUTH2", "val": { "status": "INITIATED" } },
  "status": "INITIATED",
  "redirect_url": "https://api.openconnector.dev/connect/<token>",
  "redirect_uri": "https://api.openconnector.dev/connect/<token>",
  "deprecated": { "uuid": "01j9xyz789", "authConfigUuid": "01j9abc123" }
}

查询单个连接

const account = await oc.getConnection({
  connectionId: "conn_01j9xyz789",
});

console.log(account.status);
console.log(account.providerSlug); // "github"

const account = await composio.connectedAccounts.get("conn_01j9xyz789");

console.log(account.status); // "ACTIVE" | "EXPIRED" | "INITIATED" | "REVOKED"
console.log(account.toolkit.slug); // "github"

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

响应示例：

{
  "id": "conn_01j9xyz789",
  "status": "ACTIVE",
  "state": { "authScheme": "OAUTH2", "val": { "status": "ACTIVE" } },
  "toolkit": { "slug": "github" },
  "auth_config": { "id": "ac_01j9abc123", "auth_scheme": "OAUTH2" },
  "user_id": "来自您系统的用户ID",
  "created_at": "2026-06-07T10:00:00.000Z",
  "updated_at": "2026-06-07T10:05:00.000Z"
}

列出连接

const accounts = await oc.listConnections({});

for (const account of accounts.items) {
  console.log(account.id, account.status);
}

const accounts = await composio.connectedAccounts.list({
  toolkit_slugs: "github",  // 可选：按连接器类型过滤
  user_ids: "user_123",     // 可选：按用户 ID 过滤
  limit: 20,
});

for (const account of accounts.items) {
  console.log(account.id, account.status);
}

curl "https://api.openconnector.dev/composio/api/v3.1/connected_accounts?toolkit_slugs=github&user_ids=user_123" \
  -H "x-api-key: oc_abc123xyz..."

刷新 Token

在 Token 自然过期之前强制立即刷新。在您希望提前发现 Token 已被用户从外部撤销的情况下很有用。

await oc.refreshConnection({ connectionId: "conn_01j9xyz789" });

await composio.connectedAccounts.refresh("conn_01j9xyz789");

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

撤销并删除

删除连接账户会撤销存储的 Token 并从保险库中移除。用户需要重新授权才能恢复访问。

await oc.revokeConnection({ connectionId: "conn_01j9xyz789" });
await oc.deleteConnection({ connectionId: "conn_01j9xyz789" });

await composio.connectedAccounts.delete("conn_01j9xyz789");

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

连接状态说明

以下是 Composio 兼容 API 返回的线路（wire）状态值。Open Connector 内部跟踪原生状态（pending、active、error、expired、dropped、revoked，外加 disabled 标志），API 会将其映射为下方的大写线路状态值。

Prop

Type

Open Connector 会在正常工具调用执行过程中自动刷新即将过期的 Access Token。您无需轮询过期状态或手动刷新，除非您希望主动验证连通性。

API_KEY 类型连接器的特殊说明

对于采用 API_KEY 认证方案的连接器（例如 Telegram），不存在 OAuth 重定向流程。创建连接时在 connection.state.val 中直接内联提供凭证：

curl -X POST "https://api.openconnector.dev/composio/api/v3.1/connected_accounts" \
  -H "x-api-key: oc_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "auth_config": { "id": "ac_telegram_01" },
    "connection": {
      "user_id": "来自您系统的用户ID",
      "state": {
        "val": {
          "apiKey": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
        }
      }
    }
  }'

密钥会加密存储到保险库中，redirect_url 返回 null，连接状态直接变为 ACTIVE。

On this page