Agents Overview
How AI agents authenticate with Open Connector and call tools.
Open Connector is built specifically for AI agents that need to act on behalf of users — creating GitHub issues, sending Telegram messages, and more. This section explains how agents authenticate, how they reference user credentials, and how tool calls are executed.
The agent auth model
Agents authenticate with Open Connector using a scoped API key sent in the x-api-key request header. Each key is bound to a specific Project, which in turn belongs to an Organization. The key's metadata carries both projectId and orgId, so every request is attributed to the right tenant without the agent needing to pass these values separately.
Agent request
Header: x-api-key: oc_abc123...
└─ decoded → { projectId: "proj_...", orgId: "org_..." }This model means:
- Agents never hold user OAuth tokens. Tokens are encrypted in the vault and injected server-side.
- Scoping is enforced at the key level. A key for Project A cannot access connections belonging to Project B.
- Keys are rotatable. If a key leaks, revoke it from the dashboard — existing connections are unaffected.
Typical agent workflow
Mint an agent API key
Create a key for your project from the Open Connector dashboard. Trusted administrative tools can use POST /api/v1/console/orgs/{organizationId}/projects/{projectId}/api-keys with a signed-in Console session. Store the returned key as a secret in your agent's environment.
Create a connection for each user
When a user wants to link their GitHub account, your agent (or your backend) calls POST /composio/api/v3.1/connected_accounts with the appropriate auth_config id. Open Connector returns a redirect_url. Send the user there; the callback is handled by Open Connector and the token is stored encrypted.
Call tools on behalf of the connected user
Once a connection exists, the agent calls POST /composio/api/v3.1/tools/execute/{slug} with the connected_account_id. Open Connector decrypts the token, injects it into the outbound request to the third-party API, and returns the response. The agent never sees the raw token.
SDKs
The first-party SDK uses Open Connector's native, typed API. The Composio-compatible mount remains available for existing integrations:
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",
});See SDKs for the native and compatibility surfaces.
Agent API Keys
Create and manage scoped API keys for your agents.
SDKs
Use the native Open Connector SDK or migrate an existing Composio client.
oc CLI
Discover, connect, and execute tools from a terminal or agent script.
Connected Accounts
Initiate OAuth flows and manage user connections.
Calling Tools
Execute actions via the execute endpoint with injected credentials.