DOCSEARCHbyAlgolia
Submit Docs

Nango Documentation

website·Indexed 35 days ago

https://docs.nango.dev/

An integration platform that manages complex integration tasks and provider-specific workflows. Nango provides tools for building scalable integrations with onboarding methods including manual, AI-assisted, and coding agent quickstarts.

Tokens
64K
Snippets
295
Records
399
Agent score
18%

What's inside Nango

  1. Overview of Nango integration layer

    Nango is an integration layer designed for AI-built, code-owned product integrations. It allows developers to connect users to 1,000+ external APIs while Nango handles the underlying infrastructure, including OAuth flows, API key management, token refreshes, rate limiting, retries, and tenant isolation.

    Nango operates using two core primitives:

    1. Auth: Manages connecting user accounts and storing credentials securely.
    2. Functions: TypeScript functions that execute provider-specific logic (data transformation, syncing, or actions) on production infrastructure without exposing credentials to the application.

  2. Overview of Nango Functions

    Functions are Nango's runtime for custom integration logic, written in TypeScript and deployed to Nango. They abstract away the infrastructure of integrations (OAuth, token refresh, rate limits, retries) and allow developers to focus on provider-specific logic.

    Functions can be triggered:

    • On demand (via HTTP API/SDK).
    • On a schedule.
    • Via external webhooks.
    • After connection lifecycle events.

  3. Understand Nango's Bring Your Own Cloud (BYOC) model

    Nango's BYOC model allows the Nango team to deploy and operate an instance where all resources (database, cache, compute, load balancers, and encryption keys) reside within the customer's own AWS account or GCP project. This ensures infrastructure ownership and data residency for the customer while Nango handles the operational management and on-call responsibilities.

  4. Choose a Nango integration build method

    Nango provides three ways to implement provider operations depending on the project's needs for speed, control, and dynamism:

    1. Function Templates: Best for getting started quickly using pre-built operations from the Nango catalog.
    2. Local CLI Development: The recommended path for production. Provides source control, reviewable diffs, local testing, and CI/CD integration.
    3. Functions API: Best for prototypes, operations not in the catalog, or just-in-time integrations where an agent generates behavior dynamically.

  5. Compare Nango deployment options

    Nango offers four primary deployment paths depending on the organization's needs for data residency and operational overhead:

    • Nango Cloud: Fully managed by Nango.
    • BYOC (Bring Your Own Cloud): Nango deploys and operates the instance within the customer's AWS account or GCP project. Recommended for Enterprise teams wanting infrastructure ownership without operational overhead.
    • Self-Managed: The customer deploys and operates Nango on their own infrastructure (any cloud or on-prem) using a Helm chart. High operational overhead.
    • Free Self-Hosted: A limited version for hobby projects providing only API Auth and Proxy functionality. No syncs, webhooks, or enterprise support.

  6. Nango security and compliance standards

    Nango is SOC 2 Type II certified, GDPR compliant, and HIPAA compliant (HIPAA requires the Growth add-on). Data is encrypted at rest using AES-256-GCM with envelope encryption via AWS KMS. All traffic is secured via TLS 1.2+.

  7. Implement Just-in-Time (JIT) integrations

    Nango's Functions API allows for the creation of integrations dynamically without manual codebase updates. An agent can take a text description of desired behavior, generate function code, compile it, dry run it against a connection, and deploy it directly to Nango. This is ideal for prototypes and dynamic product experiences.

  8. Inspect the public provider catalog via MCP

    Use providers_get to retrieve information about a provider. Setting include_templates to true will include the provider's available function templates in the response. This tool requires no additional environment operation permissions.
    {
  "providers_get": "Get one provider and optionally include its function templates (Permission: None)"
}

  9. Authorize users for MCP servers via Nango

    MCP Auth allows applications to authorize end users to access external Model Context Protocol (MCP) servers (e.g., Notion, Linear, HubSpot). Nango manages the OAuth flow and token storage, allowing you to call MCP server tools on behalf of the user via Nango's proxy API.

    There are two types of MCP support:

    1. Catalog MCP servers: Official servers listed in Nango's catalog. Some require manual Client ID/Secret registration in the Nango UI, while others use dynamic registration.
    2. Generic MCP Server OAuth2: Support for any server following the MCP Protocol specification.

  10. Understand the Nango Records Cache

    The records cache is an intermediate store between the external API and your application. When you call nango.batchSave() or nango.batchDelete(), data is written to this cache.

    Key Benefits:

    1. Change Detection: Nango tracks records to identify which are new, updated, or deleted, allowing your app to fetch only deltas.
    2. Reliability: Decouples your application from external API instabilities (rate limits, timeouts).

  11. Understand Nango's internal architecture

    Nango's infrastructure consists of the following components:

    • Server: Handles dashboard, API, proxy requests, and webhooks.
    • Orchestrator: Manages task scheduling and state tracking.
    • Jobs: Processes tasks and dispatches them to the Runner.
    • Runner: Executes integration code and interacts with external APIs.
    • Persist: Stores synced records and logs.
    • Postgres: Control plane data, API credentials, scheduled tasks, and synced records.
    • Object Storage (S3): Compiled integration code.
    • ElasticSearch: Customer-facing observability.
    • Redis: Caches socket info, token refresh locks, and rate limits.

  12. Access metadata inside a Nango function

    Inside a function, nango.getMetadata() automatically retrieves metadata for the connection currently being executed. You should define a metadata schema using Zod on the function to ensure type safety. Note that metadata may be cached for up to 60 seconds during a single execution.
    import { createSync } from 'nango';
import * as z from 'zod';

const Metadata = z.object({
    accountRegion: z.string().optional(),
    syncArchived: z.boolean().default(false)
});

export default createSync({
    description: 'Sync contacts',
    frequency: 'every hour',
    metadata: Metadata,
    exec: async (nango) => {
        const metadata = await nango.getMetadata();

        await nango.get({
            endpoint: '/contacts',
            params: {
                region: metadata.accountRegion,
                archived: metadata.syncArchived
            }
        });
    }
});