DOCSEARCHbyAlgolia
Submit Docs

Nango Documentation

repository·master·Indexed 27 days ago

https://github.com/nangohq/nango

An open-source platform for building product integrations, supporting over 900 APIs. Nango provides managed authentication, a proxy for authenticated API calls, and a TypeScript runtime for custom integration logic. The platform includes Nango Connect for frontend connection management, a comprehensive design system with Figma token synchronization, and the @nangohq/node SDK for credential retrieval and proxy requests.

Tokens
355.3K
Snippets
953
Records
1.7K
Agent score
95%

What's inside Nango

  1. Overview of Nango Integration Layer

    master

    Nango is an integration layer designed for building product integrations using code you control. It allows users to connect external APIs through Nango, while developers write and customize TypeScript functions to interact with those APIs.

    Nango handles the heavy lifting of integration infrastructure, including:

    • Auth: OAuth flows, API keys, token refresh, scopes, and credential storage.
    • Integration Runtime: Execution of actions, syncs, webhooks, schedules, retries, rate-limit backoff, checkpoints, and resumable execution.
    • Agent-ready Access: Tool schemas and MCP (Model Context Protocol) support for AI agents.
    • Production Controls: Observability (logs, metrics, alerts), isolated environments, tenant isolation, and CI/CD workflows.

  2. Microsoft Power BI Access Requirements

    master

    The following requirements apply to setting up the Microsoft Power BI integration:

    • Paid dev account: Not required (Free Microsoft and Azure accounts can be used).
    • Paid test account: Not required.
    • Partnership: Not required.
    • App review: Conditional (Required only if publishing to the Microsoft commercial marketplace or if admin consent is needed for specific permissions).
    • Security audit: Not required.

  4. Understand Nango Functions

    master

    Nango Functions are a TypeScript runtime for custom integration logic. They allow you to write provider-specific code while Nango manages the underlying infrastructure such as OAuth credentials, token refreshes, retries, rate limits, and observability.

    Functions run with scoped access to a specific connectionId, meaning they use the credentials of a specific customer connection without exposing those credentials to your application or AI agents.

  5. Choose a Nango function development path

    master

    Nango provides three distinct ways to enable or develop functions depending on your requirements for control and dynamism:

    1. Function Templates: Best for getting started quickly using pre-built functions from the Nango catalog. Enable a template in the dashboard and call it from your app.
    2. Local CLI Development: Best for production use cases requiring source control, testing, CI/CD, and code reviews. Write TypeScript functions in your own repository and deploy via the Nango CLI.
    3. Functions API: Best for prototypes or agentic workflows where behavior is generated dynamically. Send TypeScript source to Nango's API to compile, dry run, and deploy without a local project.

  7. How Google Calendar webhooks work with Nango

    master

    Nango enables real-time Google Calendar updates using Google's notification channels. Unlike Gmail, Google Calendar webhooks are configured by passing a webhook URL directly to the Calendar API as the channel address without requiring Google Cloud Pub/Sub.

    The Workflow:

    1. Watch: Call the Google Calendar watch endpoint with your Nango webhook URL as the address.
    2. Sync: Google creates the channel and sends an initial sync message to your URL.
    3. Notify: When the calendar changes, Google sends a notification to Nango.
    4. Forward: Nango matches the notification to the appropriate connection and forwards it to your application.

    Connection Matching: Nango identifies the calendar using the X-Goog-Resource-URI header. For the google-calendar integration, Nango automatically handles routing for new connections by persisting a hash of the user's email in connection_config.emailAddressHash during connection setup. This allows the primary calendar flow to work without additional metadata.

  8. Understand Google Drive webhook mechanics in Nango

    master

    Nango enables real-time Google Drive updates using Google's push notification system. You can implement two types of notification channels via the Drive API:

    • changes.watch: Monitors every change across a user's entire Drive or a single shared drive. This is the recommended method for most integrations.
    • files.watch: Monitors changes to one specific file only.

    The Workflow:

    1. Call the Drive API changes.watch method, providing your Nango webhook URL as the address parameter.
    2. Google creates the channel and sends an initial sync message to your Nango URL.
    3. Google sends notifications to Nango whenever changes occur in the watched Drive.
    4. Nango matches these notifications to the appropriate user connection and forwards them to your application.

    Important: Because Google Drive does not provide a built-in identifier that Nango can automatically map to a connection, you must manually store the channel's resource identifier to ensure successful connection matching.

  9. Nango Auth capabilities overview

    master

    Nango Auth provides several key features for managing external API integrations:

    • Auth schemes: Supports OAuth 2.0, OAuth 1.0a, API keys, basic auth, and custom schemes across 900+ APIs.
    • Pre-built UI: An embedded Connect UI that includes API-specific guidance, input validation, and branding options.
    • Credential management: Provides encrypted storage, automatic credential refresh, and retrieval at scale. It is recommended to use this in combination with Proxy or Functions to avoid handling raw credentials in your codebase.
    • Observability: Includes failure detection, reconnect flows, and per-connection logs.

  11. Quickstart: Integrate Prospeo with Nango

    master

    Follow these steps to connect to the Prospeo API using Nango's proxy service:

    1. Create the integration: In the Nango dashboard, navigate to Integrations -> Configure New Integration -> Prospeo.
    2. Authorize Prospeo: Go to Connections -> Add Test Connection -> Authorize, and enter your Prospeo API key.
    3. Call the Prospeo API: Use the Nango Proxy to make requests to Prospeo endpoints. You will need your Nango Secret Key, Integration ID, and Connection ID.
    4. Implement in your app: Follow the Nango Auth implementation guide to allow your users to connect their own Prospeo accounts.

  12. Quickstart: Integrate Anvil with Nango

    master

    Follow these steps to connect to the Anvil API using Nango's proxy and SDKs:

    1. Create the integration: In the Nango dashboard, navigate to Integrations -> Configure New Integration -> Anvil.
    2. Authorize Anvil: Go to Connections -> Add Test Connection -> Authorize, and enter your Anvil API key.
    3. Call the Anvil API: Use the Nango Proxy or the @nangohq/node SDK to make requests to Anvil endpoints. You will need your Nango secret key, integration ID, and connection ID.

    Once connected, you can inspect requests in the Nango Logs tab.