---
title: Core concepts
description: Distinguish the concepts shared by the three Connector products and
  the identity, permission, and runtime model each product uses.
lang: en
canonical_url: https://oomol.com/en/docs/core-concepts/
markdown_url: https://oomol.com/en/docs/core-concepts.md
---

# Core concepts

The three Connector products share providers, actions, and schemas, but they use different account isolation and permission models. Identify the product first, then interpret its connection, connected account, Team, or Project resources.

| Product | Account and isolation model | Runs in |
| --- | --- | --- |
| OOMOL Connector (Hosted) | Connections in a personal or Team scope | OOMOL-hosted |
| Connector for SaaS | Projects, external users, and connected accounts | OOMOL-hosted |
| OpenConnector | A runtime and connections managed by the operator | Your infrastructure |

## Concepts shared by all three products

### Apps and providers

An **App** is the service a user sees and chooses to connect, such as Gmail, GitHub, or Slack.

A **provider** or **service** is the corresponding Connector integration. It defines authentication, actions, schemas, and how Connector requests the upstream API. App and provider names usually match, but one is the user-facing service and the other is the Connector implementation boundary.

### Actions and tools

An **action** is one callable operation exposed by a provider. Its action ID normally combines a service and operation, such as `gmail.search_threads`. Each action has an input schema and defines the data returned by a call.

A **tool** is the calling surface through which an Agent, CLI, or MCP client sees an action. An SDK usually executes an action directly, while an Agent discovers and invokes available actions as tools.

Before execution, confirm:

- which account the action will use;
- which parameters will be submitted;
- whether the operation reads, writes, or deletes data;
- whether the current identity may use the corresponding account resource.

### Agents and Skills

An **Agent** chooses a tool, supplies parameters, and uses the result to continue a task. OOMOL supplies the authorized App capabilities used during that work.

A **Skill** is a reusable set of task instructions. It tells an Agent which tools to use, in what order, what constraints to preserve, and how to organize the result. Execution uses the Agent's identity and available tools, while Connector stores the App credentials.

## OOMOL Connector (Hosted)

### Connection

A **connection** is one connection instance for an App account in a personal or Team scope. It has its own connection name and ID and is associated with account authorization, status, and permission settings.

The same App account can be connected more than once. Each connection can separately configure:

- **Action access**: which actions the connection allows;
- **Member access**: which Team members may use the connection.

A member's callable actions are the union of the actions allowed by every connection they can access.

### Team

A **Team** is the Team tenant scope for Hosted Connector. The active Team determines which connections a caller can see and which actions within them the caller may use.

CLI, MCP, and SDK clients should select a Team explicitly so a later default-Team change does not select the wrong connection. The Team plan is billed per seat; review current details under [Billing in Console](https://console.oomol.com/billing).

### Effective access

A call can execute only within the intersection of these boundaries:

```text
Provider authorization
  ∩ connection Action access
  ∩ Team Member access
  ∩ CLI, MCP, or SDK caller identity
  = actions the caller can execute
```

See [Access control](/en/docs/access-control/) and [Team management](/en/docs/team-management/) for configuration details.

### Hosted Connector call path

```text
User connects an App
  → a connection is created
  → Agent or trusted backend selects an action and connection
  → Hosted Connector checks access and loads credentials
  → Provider API
  → result and execution metadata return to the caller
```

## Connector for SaaS

Connector for SaaS lets users of your product connect their own third-party accounts. It uses a separate multi-tenant resource model:

| Resource | Purpose |
| --- | --- |
| **Project** | Isolates configuration, keys, connected accounts, execution records, and usage for one product integration |
| **Provider config** | Defines authentication for one provider in a Project |
| **External user ID** | Maps OOMOL resources to a user in your product |
| **Connected account** | Represents a provider account authorized by one external user |
| **Project API key** | Authenticates Project requests from a trusted backend |

A **connected account** represents a provider account authorized by one external user in a Project. The backend selects it when executing an action for that product user.

### SaaS call path

```text
Product user completes Provider authorization
  → connected account is linked to an external user ID
  → your backend uses a Project API key
  → ProjectConnector selects the user, connected account, and action
  → Hosted Connector executes the call
  → Provider API
```

Your product authenticates its own users and maintains a stable, unguessable external-user mapping. See [Connector for SaaS](/en/docs/saas/) for the resource model and integration flow.

## OpenConnector

**OpenConnector** is the open-source runtime and gateway that you deploy in your own infrastructure.

- The **runtime** loads providers, manages connections, selects credentials, enforces policy, and calls Provider APIs.
- The **gateway** is the access surface the runtime exposes to MCP, HTTP, OpenAPI, and SDK clients.
- A **runtime token** controls whether a client may access the runtime and its capabilities.

OpenConnector places the runtime, connections, and access policy in infrastructure you manage. Callers use its actions through MCP, HTTP, OpenAPI, or the SDK.

### OpenConnector call path

```text
You configure a Provider and connection
  → Agent or application selects an action and connection
  → OpenConnector runtime checks the token and policy
  → runtime loads credentials and calls the Provider API
  → result returns to the caller
```

The operator is responsible for credential encryption, tokens, storage, networking, logs, backups, and upgrades. See [OpenConnector](/en/docs/openconnector/) for the full boundary.

## Credential boundary

Raw Provider OAuth tokens, API keys, and custom credentials should not be exposed to Agents, Skills, browser clients, or product users:

- OOMOL stores and refreshes credentials within the hosted boundary for Hosted Connector and Connector for SaaS;
- the OpenConnector operator protects credentials in their own infrastructure;
- Connector loads credentials when executing an action or supported proxy request and returns only the execution result to the caller.

## Choose the correct term

| Scenario | Use this term |
| --- | --- |
| An individual or Team connects an App account | connection |
| A SaaS product user connects their own account | connected account + external user |
| The isolation boundary for one SaaS integration | Project |
| Restrict account and action use within a Team | connection Member access and Action access |
| A callable entry presented to an Agent | tool |
| An operation defined by Connector | action |
| A self-hosted execution service | OpenConnector runtime / gateway |

After choosing a product, continue with its overview and integration guide. See the [TypeScript SDK reference](/en/docs/connector-sdk/) for exact methods and types.