# Nango: a self-hostable platform for product integrations, auth and proxy

> Nango is an open-source TypeScript platform that manages OAuth and credentials for 1,000+ APIs, proxies authenticated requests, and runs integration functions. It fits teams that want readable, version-controlled integration code rather than a black-box connector service.

**NangoHQ/nango** — Build product integrations with AI.

- Repository: https://github.com/NangoHQ/nango
- Website: https://nango.dev
- Stars: 12,448 · Forks: 1,397
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nangohq-nango

## The problem Nango solves for product teams

Every product that connects to external APIs eventually rebuilds the same three things: an OAuth flow, a place to store and refresh credentials per customer, and a way to call the provider without leaking tokens into your frontend. Nango's README frames this as three primitives, Auth, Proxy and Functions, and the target user is a product engineering team shipping integrations to its own customers rather than an internal data team wiring up a single pipeline.

The multi-tenant angle is the part that distinguishes it from a generic HTTP client. Connections are addressed by an integration ID and a connection ID, so one integration definition can serve many end customers, each with their own credentials. The README states that Nango handles credential storage and token refresh for 1,000+ APIs, and that the auth flow can be embedded white-label in your own app through a Connect UI component.

It is also explicitly aimed at AI-assisted development. The README describes an AI builder that generates TypeScript integration functions from a natural-language description, and lists tool calling and MCP among the supported use cases. The pitch is that the generated artifact is code you can read and version, in contrast to a hosted connector where the transformation logic stays opaque.

## Auth, Proxy and Functions: how the pieces fit together

The architecture visible in the repository is a set of npm workspaces under packages/, including server, runner, orchestrator, jobs, persist, records, database, node-client and connect-ui, with Dockerfiles for hosted and self-hosted builds. The server exposes an HTTP API on port 3003 by default and a worker on 3004, according to .env.example. Postgres backs provider configurations and credentials, and the environment sample shows a separate RECORDS_DATABASE_URL for records storage that defaults to the main database when empty.

The data flow for a proxied request is: your backend calls the Nango API with an endpoint, an integration ID and a connection ID; Nango resolves the provider configuration, injects the stored credentials, applies retries and rate-limit handling, and returns the provider's response. The README's Node example calls nango.get with endpoint, providerConfigKey and connectionId. Your code never holds the access token.

Functions are the second execution path. You export a default async function that receives a nango object, read inputs from nango.input, and call nango.get or nango.post inside it. That function is deployed to Nango's runtime, which supplies API access, retries, storage and observability. The README's GitHub example creates an issue and returns response.data. Syncs and actions are the two function categories the README links to, with syncs described as one or two-way data movement for RAG pipelines and indexing.

## Installing Nango and making a first authenticated request

The README's quickstart does not begin with a local install. It starts by signing up at app.nango.dev, creating an integration in the Integrations tab, then creating a connection on the Connections tab and completing the auth flow. That is the fastest path, and it is the one the documentation presents first.

If you want to self-host, the repository ships a docker-compose.yaml. It defines a nango-db service on postgres:16.0-alpine with POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB all set to nango, and a nango-server service using the nangohq/nango-server:hosted image, with the comment that you should pin the version using a commit hash tag or a version tag. The server reads NANGO_ENCRYPTION_KEY, the NANGO_DB_* variables, SERVER_PORT and NANGO_SERVER_URL, among others.

```bash
docker compose up -d
```

The .env.example notes that NANGO_ENCRYPTION_KEY must be a base64-encoded 256-bit key, that you cannot change it once set, and that it is also required for Connect UI because it is used to generate Connect UI sessions. It gives the generation command directly:

```bash
openssl rand -base64 32
```

On the client side, the Node package is @nangohq/node. The README constructs a client with a secret key and reads a connection's credentials, which is the quickest way to confirm that an auth flow completed and that credentials were stored:

```typescript
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

const connection = await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');
console.log(connection.credentials);
```

Once that returns credentials, the next step is a proxied call to the provider, using the same client with endpoint, providerConfigKey and connectionId. If you are embedding the flow in your own product instead of using the dashboard, the README shows nango.openConnectUI with an onEvent callback, which fires when the user completes authorization.

## Where Nango is the wrong tool

The licence is the first constraint. The README states Nango is available under the Elastic License, and the repository carries a LICENSE_SHORT file alongside LICENSE. The README's own framing is that Cloud and Enterprise Self-Hosted give access to all features based on your plan, while free self-hosting comes with a limited feature set. If your distribution model depends on a permissive OSI-approved licence, or if you need every feature without a commercial agreement, that split is the deciding factor and not something the README resolves for you.

The second constraint is operational weight. Self-hosting means Postgres plus the server, worker and supporting packages, with an encryption key you must generate and then never change. That key requirement is a real migration hazard: the .env.example warns you cannot change it once set, so losing it or rotating it carelessly has consequences for stored credentials. Teams that want a single binary or a managed service with no database to run should look elsewhere.

The third is scope. Nango is built around connecting to third-party APIs on behalf of your users. If your problem is internal workflow automation, scheduled jobs between your own systems, or a single one-off script against one vendor, the auth and multi-tenant machinery is overhead you will not use. The README's feature list is entirely oriented toward product integrations, not general automation. And the AI builder generates functions from a description, which means the quality of what you deploy still depends on your review process; the README presents readability and version control as the safeguard, which puts that responsibility on you.

## Nango compared with unified API aggregators

The most common comparison point is a unified API aggregator, the category that includes Merge. The difference is where the abstraction lives. A unified API provider owns the normalization: you call one canonical schema and the vendor maps each underlying API to it, which means you get consistency quickly but you inherit their schema, their supported field set and their pace of adding providers. Nango's README lists API unification as one use case you can build, not as the product's default mode. The default mode is that you call the provider's own endpoints through the proxy, or write a function that does the normalization yourself.

That trade-off is explicit in the README's positioning. It describes generating TypeScript you can review, edit and version control, and contrasts that with black-box solutions. If you want a canonical contact object across five CRMs without writing the mapping, an aggregator is less work. If you want the mapping to be your code, with your error handling and your field choices, Nango gives you the auth and execution layer and leaves the semantics to you.

Against a general workflow tool, the split is similar but sharper: those tools model integrations as visual steps, while Nango models them as TypeScript functions deployed to a runtime with retries, storage and per-tenant isolation. The README also positions Nango as compatible with agent SDKs and AI coding tools, so for an agent that needs to act on external APIs, the proxy plus connection model is the relevant piece rather than a visual builder.

## Maintenance, releases and licence cost

The repository is not archived, and the last push was on 2026-09-18. Releases are frequent and versioned: v0.71.9 on 2026-09-16, v0.71.8 on 2026-09-16, v0.71.7 on 2026-09-11. The 0.x major version is worth noting for upgrade planning, since minor bumps are where behavior changes tend to land in a project at this stage. The repository includes a CHANGELOG.md and a cliff.toml, which suggests release notes are generated rather than hand-written, so read the changelog before bumping.

The upgrade surface is larger than a single library because Nango is a set of workspaces plus a database. The package.json exposes migration scripts (create:migration and undo:migration) that run knex against packages/database/lib, so schema changes are part of the release process and you should expect to run migrations when you pull a new version. The Docker Compose file recommends pinning the server image by commit hash tag or version tag rather than tracking a floating tag, which is the practical way to control when a migration lands.

On licensing, the Elastic License governs the code, and the README separates free self-hosting from Cloud and Enterprise Self-Hosted plans with a limited feature set on the free path. Whether that is acceptable depends on how you ship your product, and that is a question for your own counsel rather than something the README answers.

## Conclusion

Adopt Nango if you are building a product that needs to connect to many third-party APIs and you want the auth and token-refresh layer handled while keeping integration logic as reviewable TypeScript. Skip it if you need a permissive OSI licence or cannot run Postgres and the other services the stack expects. Before committing, check the Elastic License against your distribution model, confirm which features the free self-hosting path includes, and decide whether you will run Nango Cloud or the Docker Compose stack.

## FAQ

### Is Nango free to use?

The README states that Nango is available under the Elastic License, that Cloud and Enterprise Self-Hosted give access to all features based on your plan, and that you can self-host for free with a limited feature set. Signing up for the hosted app is described as free with no credit card.

### How does Nango work?

Nango provides three primitives: Auth, which manages OAuth, API keys and token refresh for 1,000+ APIs; Proxy, which makes authenticated requests on behalf of your users by resolving the provider and injecting credentials; and Functions, TypeScript integration logic deployed to Nango's runtime.

### What is Nango?

Nango is an open-source platform for building product integrations, supporting 1,000+ APIs and working with any backend language, AI coding tool or agent SDK. You write integration logic as TypeScript functions and deploy to Nango's production runtime, which handles auth, execution, scaling and observability.

### What are the alternatives to Nango?

The README positions Nango against black-box integration solutions and notes it can be self-hosted or run on Nango Cloud. Its API unification use case overlaps with unified API aggregators, but Nango leaves the normalization to functions you write rather than owning a canonical schema, and it is also compatible with agent SDKs and AI coding tools.

## Sources

- [Issues](https://github.com/NangoHQ/nango/issues)
- [NangoHQ/nango on GitHub](https://github.com/NangoHQ/nango)
- [Project website](https://nango.dev)
- [README](https://github.com/NangoHQ/nango/blob/master/README.md)
- [Releases](https://github.com/NangoHQ/nango/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nangohq-nango