Crafting Integrations with Nango

Working on integrations with Nango? You’re in luck! A whopping 95% of the work is already done for you. Nango provides all the intricate infrastructure required for integrations (feature list).

All that’s left for you is to code the remaining 5% that is unique to your integration:

  • What data do you want to sync?
  • How should this data be transformed? What should be the final data model?
  • What data do you need to write back and when?

With this, Nango creates a fully-typed SDK and ensures your integrations run seamlessly in production.

Understanding the Architecture

API Authorization

Users can authorize integrations within your app via an OAuth popup. This is as simple as making a call to the frontend SDK.

Nango handles the acquisition, storage, and refreshing of API credentials.

You can then retrieve always fresh API access tokens via the backend SDKs or API.

OAuth Architecture

Continuous Syncs

Nango enables you to specify how data syncs with external APIs, for instance, fetching Salesforce contacts or Google Calendar events. You define these syncs, and they live in your repository, version-controlled along with the rest of your codebase.

We offer Integration templates for common use cases and tools to assist you in writing and testing syncs locally (consult the syncs guide).

Once your syncs are ready, you deploy them to Nango via a CLI command. Nango then takes over, running them in production, handling scaling, scheduling, retries, data caching, de-duplication, and more.

Continuous Sync Architecture

Proxy Requests

There might be times when you want to make one-off API requests, for instance:

  • Writing data back on an as-needed basis
  • Fetching data that doesn’t need continuous syncing (e.g., for onboarding)

The Proxy simplifies this process, offering benefits such as authorization, retries, rate-limit handling, and monitoring.

For examples and more details, check out the Proxy guide.

Proxy Architecture


Nango supports two kinds of webhooks:

  • External webhooks: these go from the external API to Nango, notifying of data changes in real-time
  • Nango webhooks: these go from Nango to your app, notifying your app that new data is available (upon sync job completion or external webhook reception)

Webhooks Architecture

To learn more, refer to the Webhooks guide

Dashboard: Sync Monitoring & Management

The Nango Dashboard provides a detailed activity log for every sync and proxy request. Here, you can view comprehensive logs of every sync run and even log your messages from sync scripts.

Activity overview of syncs

Furthermore, you can view and manage the syncs for each connection (integration setup by a user).

Syncs for a connection


Frequently used terms:

API Configurations

An API configuration (like the hubspot configuration) holds the specific Nango configuration for an external API. This includes:

  • Auth-related configuration (auth type, OAuth URLs, auth quirks, etc.)
  • Sync-related configuration (rate-limits, pagination strategy, etc.)

These configurations, contributed and regularly improved by Nango and its community, enable rapid adaptation of Nango to work with any API via editing a .yaml configuration file.

For more information and to contribute API configurations, click here.


Developers create integrations, based on API configurations, to work with external APIs from their app.

Integrations are created by you in the Nango Dashboard. You then control how they work with syncs and our SDKs or REST APIs.


When a user of your app authorizes an integration, Nango calls this a new connection: E.g. user1 authorizes a Github integration to sync issues in your app.

Connections represent the relation between an end user and an external API. It contains the necessary credentials to access the external API on behalf of the user together with metadata and per-user configuration.


Syncs are responsible to continuously synchronize data between an external API and Nango. Each sync has:

  • an entry in the nango.yaml configuration file in the nango-integrations folder
  • a sync file (typescript script) in the nango-integrations folder Syncs have ‘runs’ or ‘jobs’ that are executed periodically. They can be managed (stopped, paused, resync, etc.) from the Dashboard or your code (with the SDK/REST API).