After a user completes an authorization flow, Nango creates a connection that stores their credentials for a specific integration. This guide covers the operations you can perform on connections from your backend using the Node SDK or REST API.Install the Node SDK if you haven’t already:
npm install @nangohq/node
Initialize the client with your secret key:
import { Nango } from '@nangohq/node';const nango = new Nango({ secretKey: process.env['NANGO_SECRET_KEY'] });
Retrieve a list of all connections in your environment, optionally filtered by connection ID, integration, or tags:
TypeScript
cURL
// List all connections.const result = await nango.listConnections();// Filter by integration.const result = await nango.listConnections({ integrationId: 'github'});// Filter by tags (AND match — all provided tags must match).const result = await nango.listConnections({ tags: { end_user_id: '<END-USER-ID>', organization_id: '<ORGANIZATION-ID>' }, limit: 100});console.log(result.connections);
# List all connections.curl --request GET \ --url 'https://api.nango.dev/connections' \ --header 'Authorization: Bearer <NANGO-SECRET-KEY>'# Filter by tag.curl --request GET \ --url 'https://api.nango.dev/connections?tags[end_user_id]=<END-USER-ID>&tags[organization_id]=<ORGANIZATION-ID>' \ --header 'Authorization: Bearer <NANGO-SECRET-KEY>'
Retrieve a specific connection including its current, valid credentials. Nango automatically refreshes OAuth tokens before returning them if they are expired or close to expiry.
TypeScript
cURL
const connection = await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');// The credentials object type depends on the integration's auth type.console.log(connection.credentials);console.log(connection.tags);console.log(connection.metadata);
For OAuth 2.0 connections, the credentials object includes access_token and raw (the full token response from the provider). For API key connections, it includes apiKey. For basic auth, it includes username and password.Force a token refresh by passing forceRefresh: true:
Get just the access token (OAuth 2.0) or API key as a string:
const token = await nango.getToken('<INTEGRATION-ID>', '<CONNECTION-ID>');// Returns the access_token string for OAuth2, or the ApiKeyCredentials object for API key auth.
Deleting a connection also deletes all data synced through Nango for that connection. Use re-authorization instead if you want to update credentials without losing data. See Implement auth.
Metadata is arbitrary key-value data you can attach to a connection. Use it to store per-connection configuration, such as a user’s preferences or API-specific settings.Set metadata (replaces all existing metadata):
Tags are key-value strings that attribute a connection to entities in your system — users, organizations, workspaces, and so on. They are set when creating a connect session and copied to the resulting connection.
Nango uses random UUIDs as connection IDs. Tags bridge the gap between a Nango connection ID and the entities in your application. Their primary purpose is attribution: when a user completes auth, Nango sends a webhook containing the tags you set, letting you match the connectionId with the right user or org.Tags are also useful for:
Filtering connections via listConnections() to find all connections for a given user or organization
Navigating the Nango dashboard — all tags are displayed on the Connections page
Routing webhooks or background jobs based on connection context
To update tags after a connection is created, patch the connection. Updating tags replaces the entire tag object, so include all tags you want to keep:
