| name | nango-integrations |
| description | Build third-party API integrations using Nango — managed OAuth, authenticated proxy requests, and continuous data syncs from 600+ APIs. Use when connecting to Slack, Gmail, Google Docs, Google Calendar, Google Drive, Linear, PostHog, Metabase, or any external API where you need user auth flows, token management, data syncing, or proxy requests. Covers Auth (OAuth 2.0, API keys), Proxy (authenticated pass-through), Functions (syncs + actions), and the AI integration builder. |
Nango Integrations Platform
Nango handles OAuth flows, credential storage/refresh, authenticated API requests, and continuous data syncing for 600+ APIs. You write the integration logic as TypeScript Functions; Nango manages auth, retries, rate limits, and caching.
When to read what
| Task | Read |
|---|
| Any Nango work | This file (always read first) |
| Setting up auth, connections, frontend embed | AUTH.md |
| Making authenticated API requests | PROXY.md |
| Syncing data continuously from APIs | SYNCS.md |
| One-off API actions (write/send/create) | ACTIONS.md |
| Integration configs for specific APIs | INTEGRATIONS.md |
Core concepts
Integrations — a configured API provider (e.g., slack, google-mail). Set up in the dashboard with client ID/secret and scopes.
Connections — one user's credentials for one integration. Created after a successful auth flow. Nango keeps tokens refreshed automatically.
Proxy — make authenticated API requests through Nango without handling credentials in your code. Nango injects the right tokens.
Functions — TypeScript code that runs on Nango's infrastructure. Two types:
- Syncs — run on a schedule, fetch data, cache it in Nango. You get webhooks when new data arrives.
- Actions — run on demand, perform a single API operation (send message, create issue, etc).
Architecture for data ingestion
External APIs (Slack, Gmail, GCal, GDocs, etc.)
│
▼
┌─────────────────────────────────────────────┐
│ Nango Cloud │
│ ┌─────────┐ ┌────────┐ ┌──────────────┐ │
│ │ Auth │ │ Proxy │ │ Functions │ │
│ │ (OAuth) │ │ (HTTP) │ │ (Syncs/Acts) │ │
│ └────┬────┘ └───┬────┘ └──────┬───────┘ │
│ │ │ │ │
│ └────────────┴──────────────┘ │
│ │ │
│ Records Cache (encrypted) │
└────────────────────┬────────────────────────┘
│ webhook + REST API
▼
Your App (Tasuke)
Quick start
1. Install
npm install @nangohq/node
npm install @nangohq/frontend
2. Initialize
import { Nango } from '@nangohq/node';
const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });
3. Trigger auth (frontend)
import Nango from '@nangohq/frontend';
const nango = new Nango({ connectSessionToken: '<SESSION-TOKEN>' });
nango.openConnectUI({
onEvent: (event) => {
if (event.type === 'connect') {
console.log(event.payload.connectionId, event.payload.providerConfigKey);
}
},
});
4. Get connection credentials (backend)
const connection = await nango.getConnection('slack', 'user-123');
console.log(connection.credentials);
5. Make a proxy request
const response = await nango.proxy({
method: 'GET',
endpoint: '/api/conversations.list',
providerConfigKey: 'slack',
connectionId: 'user-123',
});
6. Fetch synced records
const result = await nango.listRecords({
providerConfigKey: 'google-mail',
connectionId: 'user-123',
model: 'GmailMessage',
});
CLI essentials
npx nango init
npx nango dev
npx nango dryrun <sync-name> '<connection-id>'
npx nango deploy dev
npx nango deploy prod
Environments
Each Nango account has isolated dev and prod environments. Each has its own secret key, integrations, connections, and deployed functions. Always deploy to dev first, test, then promote to prod.
Critical rules
-
Never store Nango secret keys in client-side code. The secret key grants full access to all connections. Use it only in backend/server code. For frontend auth flows, generate a short-lived connect session token from your backend.
-
Use the Proxy instead of raw credentials whenever possible. nango.proxy() handles token injection, refresh, and retries. Fetching credentials with getConnection() then making your own HTTP call bypasses Nango's rate-limit handling and retry logic.
-
Synced records have retention limits. Records not updated for 30 days get their payload pruned. Syncs not run for 60 days get all records deleted. Always fetch records promptly after webhook notifications and store them in your own database — don't use Nango's cache as your primary data store.
-
Use cursor-based synchronization for reliability. Webhooks can be missed. Track the _nango_metadata.cursor of the last-fetched record. Pass it on subsequent fetches to get only new/modified records.
-
Use checkpoints in syncs to avoid re-fetching everything. Save progress (last timestamp, cursor, page token) with nango.saveCheckpoint(). On next run, nango.getCheckpoint() resumes from where you left off.
-
Match your integration ID to the Nango dashboard exactly. The folder name under nango-integrations/ must match the integration ID configured in the Nango dashboard (e.g., slack, google-mail, linear).
-
Use nango.batchSave() in syncs, not individual saves. Batch operations are significantly more efficient and required for Nango's change-detection (additions, updates, deletes) to work correctly.
Project structure (nango-integrations folder)
nango-integrations/
├── .nango/
├── .env # NANGO_SECRET_KEY, connection IDs for testing
├── index.ts # imports all sync/action files
├── package.json
├── slack/
│ ├── syncs/
│ │ └── slack-messages.ts
│ └── actions/
│ └── slack-send-message.ts
├── google-mail/
│ └── syncs/
│ └── gmail-messages.ts
├── google-calendar/
│ └── syncs/
│ └── gcal-events.ts
├── google-docs/
│ └── syncs/
│ └── gdocs-documents.ts
└── linear/
└── syncs/
└── linear-issues.ts
Security
Nango is SOC 2 Type II, GDPR, and HIPAA compliant. Credentials are encrypted at rest with AES-256-GCM. All transit uses TLS 1.2+. Environments are fully isolated.
IP allowlist (if your APIs need it): 52.34.139.153, 54.69.127.183, 44.247.133.183, 52.26.211.56
AI builder
Generate sync/action code with AI agents (Claude Code, Cursor, Copilot, etc.):
- Use Nango's MCP:
https://nango.dev/docs/mcp
- Install function builder skill:
npx skills add NangoHQ/skills
The AI builder feeds Nango's interface, best practices, and test patterns to your model. It generates code with proper pagination, error handling, and rate limiting.
Official docs
