---
title: Call connected Apps with the SDK
description: Use the hosted Connector client to call Apps connected to your
  OOMOL account from trusted TypeScript backend code.
lang: en
canonical_url: https://oomol.com/en/docs/connector-client/
markdown_url: https://oomol.com/en/docs/connector-client.md
---

# Call connected Apps with the SDK

Use `Connector` when backend code needs to call Apps connected to your own OOMOL account. This path uses the hosted OOMOL Connector gateway and a personal API key shaped like `api_…`.

## Install the SDK

```sh
npm install @oomol-lab/connector
```

The SDK requires Node 18 or later. It also runs in other environments that provide standard `fetch` and `AbortController` APIs, but the personal API key must remain in a trusted backend environment.

## Create a personal API key

Create a key in [OOMOL Console](https://console.oomol.com/api-key), then store it as a backend secret:

```sh
export OOMOL_API_KEY=api_...
```

Do not place this key in a browser bundle, mobile client, public repository, prompt, or client-side log.

## Execute the first action

```ts
import { Connector } from "@oomol-lab/connector";

const oomol = new Connector({ apiKey: process.env.OOMOL_API_KEY! });

const result = await oomol.execute("gmail.search_threads", {
  query: "is:unread",
});
```

The namespace form executes the same action:

```ts
const result = await oomol.gmail.search_threads({ query: "is:unread" });
```

Use `executeRaw` when you also need `executionId`, `actionId`, and the response message for logs or support.

## Select a connected account

When the same provider has multiple connections, select one with `connectionName`:

```ts
await oomol.execute(
  "gmail.search_threads",
  { query: "from:ceo" },
  { connectionName: "work" },
);
```

Use `oomol.apps.list()` to inspect the connections available to the current OOMOL account. Connection creation and removal remain in OOMOL Console.

## Discover actions

Use the catalog to inspect providers, actions, and their runtime schemas:

```ts
const providers = await oomol.catalog.providers({ q: "mail" });
const actions = await oomol.catalog.actions("gmail");
const action = await oomol.catalog.action("gmail.search_threads");
```

When an upstream endpoint does not have a modeled action, use `proxy` to call it through the selected connection.

## Continue with the reference

See the [TypeScript SDK reference](/en/docs/connector-sdk/) for precise action types, configuration precedence, retries, timeouts, cancellation, proxy behavior, errors, and the complete `Connector` API.

Use [ProjectConnector](/en/docs/project-connector/) instead when each user of your product must connect a separate account.