Core Concepts

Open Connector is built around five entities that work together to broker credentials between AI agents and third-party APIs. Understanding how they relate makes every API call and dashboard action predictable.

Entity hierarchy

Organization
└── Project  (one or more)
    ├── Auth Config  (one per service, e.g. GitHub)
    │   └── Connection  (one per user per Auth Config)
    └── Agent API Keys  (one or more, scoped to this project)

When an agent makes a tool call, the request travels through this hierarchy:

Agent
  │  x-api-key header
  ▼
Open Connector API
  │  resolves Project from key metadata
  ▼
Connection  (looked up by connectionId + projectId)
  │  decrypts credential from vault
  ▼
External API  (GitHub, Telegram, etc.)
  │  returns response
  ▼
Agent  (receives result — never the raw token)

Organization

An Organization is the top-level tenant. It maps to a company, team, or product line. All billing, member access, and audit logs are scoped to an organization.

• Every user account belongs to one or more organizations
• Projects, auth configs, and connections are all owned by an organization
• The audit log is queryable at the organization level

Project

A Project is a logical grouping within an organization. It is the unit of isolation for agent access.

• Agent API keys are minted per project
• A key for Project A cannot access connections in Project B
• You might create one project per product, per environment (staging/production), or per agent team

Example projects:

• customer-support-agents — agents that handle support tickets
• devops-agents — agents that manage GitHub repositories and issues
• data-agents-prod — production data pipeline agents

Auth Config

An Auth Config stores the OAuth app credentials (or API key configuration) for a specific service, scoped to a project.

For OAuth2 services like GitHub, an Auth Config holds your:

• OAuth client ID and client secret
• Requested scopes
• Connector slug (e.g. github)

One Auth Config can serve many Connections. If 500 users connect their GitHub accounts, they all share the same Auth Config (your GitHub OAuth app) but each have their own Connection record with their own encrypted token.

Connection

A Connection is a specific user's linked account for a service. It is the record that holds (encrypted) the OAuth token, refresh token, expiry, and associated metadata for one user + one Auth Config.

Internally, a connection carries one of these native status values (plus a separate disabled flag):

The Composio-compatible API surface reports these as wire statuses (uppercase) — this is what SDK and HTTP responses show:

Open Connector manages token refresh automatically. When a tool call is made against an active connection with an expired access token, Open Connector silently refreshes it using the stored refresh token before forwarding the request.

Tool Call

A Tool Call is an agent-initiated action brokered through a connection. The agent specifies a connectionId and an action (e.g. create_issue); Open Connector:

1. Verifies the agent key is valid and belongs to the correct project
2. Looks up the connection and verifies it belongs to the same project
3. Decrypts the credential from the AES-256-GCM vault
4. Constructs the outbound request to the external API, injecting the credential
5. Forwards the response back to the agent
6. Writes a structured audit event to the hash-chained audit log

The agent receives only the API response — never the raw credential.

Data flow: end to end

Here is the complete flow from an agent making a request to receiving a response:

Summary table