> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Functions guide

> Understand Nango Functions and choose the right way to start using them.

## Overview

**Functions** are Nango's runtime for custom integration logic.

When you build integrations directly, every provider forces you to solve the same hard problems: OAuth credentials, token refresh, per-customer permissions, retries, rate limits, data freshness, observability, and safe execution. Nango handles that infrastructure, and functions let you write the provider-specific logic that is unique to your product.

You can use Nango-maintained catalog tools directly, enable sync templates, or write and deploy your own functions. Your app can call functions from any language, framework, backend job, or agent workflow. Each execution runs for a specific integration and connection, so the function has scoped access to the right customer's credentials without exposing those credentials to your app or agent.

## How functions fit

1. Your user authorizes an external API through [Nango Auth](https://nango.dev/docs/guides/auth/auth-guide.md).
2. Your app stores the resulting `connectionId`.
3. You use a catalog tool, enable a sync template, or deploy a custom function for the integration.
4. Nango runs the function on demand, on a schedule, from an external webhook, or after a connection lifecycle event.
5. Your app receives the function result, sync records, or webhooks from Nango.

Functions are the right layer when you need custom API logic, data syncing, webhook processing, AI tools, or per-customer integration behavior.

## Capabilities

* **Scoped external API access** — run API calls with the credentials and scopes of one connection.
* **Any app stack** — trigger functions through HTTP APIs or SDKs from any backend language.
* **Multiple trigger types** — call functions on demand, run them on a schedule, route external webhooks into them, or react to connection lifecycle events.
* **Agent-ready tools** — expose selected functions to agents through the API or Nango's MCP server while keeping provider credentials out of the model loop.
* **Built-in integration infrastructure** — retries, rate-limit handling, logs, OpenTelemetry export, records storage, checkpoints, and per-connection metadata.
* **Flexible development workflows** — use catalog tools directly, enable sync templates, build through the Functions API, or keep function code in a local CLI project.

## Guide

### Ways to use or develop functions

There are three ways to use or develop Nango functions. Start with the path that matches how much control and dynamism you need.

| Path | Best for | How it works |
| - | - | - |
| [Option 1: Use the template catalog](#use-function-templates) | Getting started quickly when Nango already has the provider operation in the catalog. | Use catalog tools, or enable a sync template. |
| [Option 2: Build locally with the CLI](#build-locally-with-the-cli) | Serious production use cases where you want reviewable diffs, tests, CI/CD, and source control. | Write TypeScript functions in your repo, dry run them against real connections, and deploy with the Nango CLI. |
| [Option 3: Build with the Functions API](#build-with-the-functions-api) | Prototypes, provider operations not covered by templates, and just-in-time integrations where an agent creates behavior dynamically. | Send generated TypeScript source to Nango, compile it, dry run it, and deploy it without a local functions project. |

### Option 1: Use the template catalog

The template catalog contains pre-built Nango functions for common provider operations. Catalog tools are available out of the box and update automatically. Sync templates must be enabled before they run.

> [!NOTE]
>
> **Catalog tools and stability.** Catalog tools are maintained by Nango and update automatically. Their input schema, output shape, and behavior may change as the catalog evolves. They are best suited to agentic workflows, such as MCP tool calling. If deterministic application code needs a stable contract, [pull the tool into your functions project and deploy it](#extend-a-template). The deployed function becomes your owned implementation and no longer follows catalog updates.

You can find templates in the [integrations catalog](https://nango.dev/api-integrations) and in the integration page of the Nango dashboard.

You can use catalog tools with [Agent sessions](https://nango.dev/docs/guides/agent-sessions.md) or call them directly from your backend. For deterministic application code, [pull and deploy it](#extend-a-template) to avoid unexpected changes.

When a sync template matches your use case, enable it on the integration. If a sync template is close but not exact, [pull it into a local functions project and customize it](#extend-a-template).

#### Extend a template

Use the CLI to pull a function's code into your local functions project. Pull from the public catalog with `--catalog` (add `--target <integration-id>` if your integration ID isn't the provider name), or pull the version currently served by an environment with `--env`:

```bash theme={null}
nango pull github list-repos --catalog
nango pull github list-repos --env dev
```

`nango pull` writes the function file and adds its import to `index.ts`. After pulling, review the source and schemas, adjust inputs, outputs, record models, metadata, or provider mapping logic, then run `nango dryrun` and deploy with `nango deploy`.

> [!TIP]
>
> Pull a pre-built function when you need custom fields, a smaller output shape, customer-specific filtering, different retry behavior, or a provider workflow that is close to the catalog but not identical.

### Option 2: Build locally with the CLI

Local development is the default path for production integrations. Use it when your engineering team wants function code in source control, reviewable diffs, local tests, CI/CD, and a stable project layout.

Install skill to build locally
Copy the command for the local CLI workflow.

**1. Install and initialize**

Install the Nango CLI globally:

```bash theme={null}
npm install -g nango
```

Initialize your integrations folder at the root of your repo and commit it to source control:

```bash theme={null}
nango init nango-integrations
```

This creates a `nango-integrations/` folder with example configuration. The `.nango` subdirectory must be committed because the CLI uses it to track deployed state.

**2. Configure API keys**

Add your [API keys](https://nango.dev/docs/reference/backend/http-api/api-keys.md) to a `.env` file inside `nango-integrations/`. The CLI currently reads these API keys from `NANGO_SECRET_KEY_<ENV_NAME>` variables:

```bash theme={null}
NANGO_SECRET_KEY_PROD='<PROD-API-KEY>'
NANGO_SECRET_KEY_DEV='<DEV-API-KEY>'
```

Get your [API keys](https://nango.dev/docs/reference/backend/http-api/api-keys.md) from **Environment Settings > API Keys**. Despite the variable name, each value stores a [Nango API key](https://nango.dev/docs/reference/backend/http-api/api-keys.md). The CLI picks up the matching key for whichever environment you deploy to.

`nango init` creates `nango-integrations/.gitignore` with `.env` ignored. Keep the `.env` file untracked so [Nango API keys](https://nango.dev/docs/reference/backend/http-api/api-keys.md) are not committed.

> [!NOTE]
>
> Keys are matched by environment name: `NANGO_SECRET_KEY_<ENV_NAME>`. If you rename an environment in the UI, update the variable name in `.env` to match.
>
> For example, an environment named `staging` needs:
>
> ```bash theme={null}
> NANGO_SECRET_KEY_STAGING='<STAGING-API-KEY>'
> ```

> [accordion] Team setup
>
> Use a shared environment (usually `dev`) for day-to-day collaboration. Create personal test connections with [per-connection webhook URL overrides](https://nango.dev/docs/guides/platform/webhooks-from-nango.md#override-webhook-urls-per-connection) pointing at your local webhook endpoint, and deploy functions granularly (`nango deploy <env> <file>` / `--integration`) so teammates don't overwrite each other. See [Engineering collaboration](https://nango.dev/docs/guides/platform/environments.md#engineering-collaboration).
> Use CI to do full deploys across stable environments (like `staging` or `prod`). See the [CI/CD guide](https://nango.dev/docs/guides/functions/ci-cd.md).

> [accordion] For agents
>
> Run `nango init nango-integrations` to scaffold the folder. Ask the user for their [Nango API key](https://nango.dev/docs/reference/backend/http-api/api-keys.md) from **Environment Settings > API Keys** and write it to the matching `NANGO_SECRET_KEY_<ENV_NAME>` variable in `nango-integrations/.env`. Confirm that `nango-integrations/.gitignore` ignores `.env`.
>
> For additional context while building, add Nango's documentation MCP server (`https://nango.dev/docs/mcp`) and install the local builder skill:
>
> ```bash theme={null}
> npx skills add NangoHQ/skills -s building-nango-functions-locally
> ```

**3. Understand the folder layout**

A Nango integrations folder is a small TypeScript project. The root contains shared project files, and each integration gets its own folder named after the integration ID.

Inside each integration folder, keep function files grouped by type. Sync functions live in `syncs/`, tools in `tools/`, and event functions in `on-events/`. This keeps the trigger model visible from the file path and matches how the CLI discovers function code.

The root `index.ts` is the deployment entry point. It should import every function file you want Nango to compile and deploy, for example `import './github/syncs/github-issues';`. Files that are not imported from `index.ts` are not part of the deployed function set.

The `.nango/` folder stores CLI-managed project state, including deployment tracking. Commit it so teammates and CI deploy from the same baseline.

```
nango-integrations/
├── .nango/                        # auto-managed state, commit it
├── .env                           # API keys per environment
├── .gitignore                     # keeps .env and dist untracked
├── index.ts                       # imports every function file
├── package.json
└── <integration-id>/              # one folder per integration, e.g. github
    ├── syncs/
    │   └── github-issues.ts
    ├── tools/
    │   └── github-create-issue.ts
    └── on-events/
        └── post-connection-creation.ts
```

**4. Run dev mode**

Keep dev mode running while you write code:

```bash theme={null}
nango dev
```

`nango dev` continuously type-checks and compiles your function files, surfacing errors immediately.

**5. Build the function**

Choose the right function type for your integration use case:

| If you need to... | Use | Common trigger | Guide |
| - | - | - | - |
| Keep external API data fresh, replicate records, or reconcile changes | Sync function | Schedule, manual sync trigger, or external webhook reconciliation | [Sync functions](https://nango.dev/docs/guides/functions/syncs/sync-functions.md) |
| Run an operation when your app, backend job, or agent asks for it | Tool | HTTP API, SDK, or MCP tool call | [Tools](https://nango.dev/docs/guides/functions/tools.md) |
| Process an external provider webhook inside Nango | Webhook function | External API webhook | [Webhook functions](https://nango.dev/docs/guides/functions/webhook-functions.md) |
| React to Nango connection lifecycle events | Event function | Connection creation, validation, or deletion | [Event functions](https://nango.dev/docs/guides/functions/event-functions.md) |

For shared primitives, use [Storage](https://nango.dev/docs/guides/functions/storage.md) for connection metadata and [Data validation](https://nango.dev/docs/guides/functions/data-validation.md) for function input, output, and provider response validation.

**6. Test and deploy**

Dry run a function against a real connection:

```bash theme={null}
nango dryrun <function-name> '<CONNECTION-ID>' -e dev
```

If the function reads connection metadata, pass test metadata:

```bash theme={null}
nango dryrun <function-name> '<CONNECTION-ID>' -e dev --metadata '{"accountRegion":"eu"}'
```

Deploy the function you changed:

```bash theme={null}
nango deploy dev <integration-id>/<folder>/<file>.ts
# or
nango deploy --integration <integration-id> dev
```

A bare `nango deploy` reconciles all functions deployed from a CLI project: it deploys functions present locally and removes remote ones that aren't. This can delete teammates' functions in a shared environment. See [Engineering collaboration](https://nango.dev/docs/guides/platform/environments.md#engineering-collaboration).

For function-type-specific commands, see the [Sync function guide](https://nango.dev/docs/guides/functions/syncs/sync-functions.md#test-and-deploy), [Tool guide](https://nango.dev/docs/guides/functions/tools.md#test-and-deploy), and [Testing](https://nango.dev/docs/guides/functions/testing.md).

### Option 3: Build with the Functions API

Use the Functions API when an agent should create or change an integration without the user working in a codebase. The agent might be Codex, Claude Code, Cursor, or a product agent running inside your app or sandbox.

This is useful for prototypes, onboarding flows, provider operations not covered by templates, and just-in-time integrations where users describe behavior in text and an agent publishes the matching function to Nango.

Install skill to build remotely
Copy the command for coding agents using the Functions API workflow.

> [!NOTE]
>
> The source-code Functions API supports sync functions, tools, and deprecated actions.

At a high level, the flow is:

1. Give the agent the integration ID, a connection ID for validation, the intended behavior, input and output shape, and any provider API context.
2. The agent generates a self-contained TypeScript function using the right function type.
3. Compile the source with `POST /functions/compile`. Send the TypeScript source as `code` and use compiler errors to improve it.
4. Start a dry run with `POST /functions/dryruns`. Send the integration ID, function type, source `code`, connection ID, and any function input, sync metadata, or checkpoint payload needed for the run.
5. Poll `GET /functions/dryruns/{id}` until the dry run reaches `success` or `failed`, then inspect the result, logs, records, or error.
6. Deploy it with `POST /functions/deployments`. Send `type: "function"`, the integration ID, function name, function type, and final source `code`. After deployment, your app can call or trigger the function like any other Nango function.

Resolve these endpoints against `NANGO_SERVER_URL`, or `https://api.nango.dev` by default. Send `Authorization: Bearer <NANGO-API-KEY>` and `Content-Type: application/json`. Scoped API keys need `environment:functions:compile` for compile, `environment:functions:dryrun` for dry run creation and polling, and `environment:deploy` for deployment.

The Functions API is powerful, but it intentionally skips a local Git workflow. For production integrations that need code review, tests, ownership, and CI/CD, prefer [local development with the CLI](#build-locally-with-the-cli).

### Take ownership of a function

Pull a function into your local functions project so you can manage it in your own repository. Use `--env` to pull the version served by an environment, or `--catalog` to pull the public catalog version:

```bash theme={null}
nango pull github list-repos --env dev
nango pull github list-repos --catalog
```

`--env` works for any function served by an environment, including a catalog tool or code deployed through [`POST /functions/deployments`](https://nango.dev/docs/reference/backend/http-api/functions/deployments-create).

The CLI writes the function's TypeScript source locally; from there, `nango deploy` redeploys it as a repo-managed function, so it lives in your Git workflow with code review, tests, and CI/CD.

## Related guides

* [Function tool calling](https://nango.dev/docs/guides/agent-sessions.md) — expose tools to agents, LLM SDKs, and MCP clients.
* [Unified APIs](https://nango.dev/docs/guides/functions/unified-apis.md) — build provider-specific functions behind one stable model.
* [Logging](https://nango.dev/docs/guides/functions/logging.md) — control custom function logs locally and in cloud environments.
* [Storage](https://nango.dev/docs/guides/functions/storage.md) — store per-connection metadata and read it inside functions.
* [Data validation](https://nango.dev/docs/guides/functions/data-validation.md) — validate function input, output, and provider API responses.
* [Testing](https://nango.dev/docs/guides/functions/testing.md) — dry runs, mocks, and snapshot tests.
* [Rate limits](https://nango.dev/docs/guides/functions/rate-limits.md) — handle provider `429` responses and long-running retries.
* [CI/CD](https://nango.dev/docs/guides/functions/ci-cd.md) — deploy functions with your application pipeline.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.