Connection management

Overview

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'] });

List connections

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>'

Example response:

{
  "connections": [
    {
      "id": 1,
      "connection_id": "<CONNECTION-ID>",
      "provider": "github",
      "provider_config_key": "github",
      "created": "2026-01-01T00:00:00.000Z",
      "metadata": null,
      "tags": {
        "end_user_id": "<END-USER-ID>",
        "organization_id": "<ORGANIZATION-ID>"
      },
      "errors": []
    }
  ]
}

Get a connection and its credentials

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);

curl --request GET \
  --url 'https://api.nango.dev/connections/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID>' \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>'

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:

const connection = await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>', 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.

Delete a connection

Deleting a connection removes all credentials and associated data. This cannot be undone.

TypeScript
cURL

await nango.deleteConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');

curl --request DELETE \
  --url 'https://api.nango.dev/connections/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID>' \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>'

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.

Set and update metadata

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):

TypeScript
cURL

await nango.setMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>', {
  accountType: 'enterprise',
  region: 'us-east-1',
  webhookUrl: 'https://example.com/hooks'
});

curl --request POST \
  --url 'https://api.nango.dev/connections/metadata' \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider_config_key": "<INTEGRATION-ID>",
    "connection_id": "<CONNECTION-ID>",
    "metadata": {
      "accountType": "enterprise",
      "region": "us-east-1"
    }
  }'

Update metadata (merges with existing metadata, overriding only specified keys):

TypeScript
cURL

await nango.updateMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>', {
  region: 'eu-west-1'
});

curl --request PATCH \
  --url 'https://api.nango.dev/connections/metadata' \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider_config_key": "<INTEGRATION-ID>",
    "connection_id": "<CONNECTION-ID>",
    "metadata": {
      "region": "eu-west-1"
    }
  }'

Read metadata from a connection:

const metadata = await nango.getMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>');
console.log(metadata); // { accountType: 'enterprise', region: 'eu-west-1', ... }

You can also type the return value:

interface MyMetadata {
  accountType: string;
  region: string;
  webhookUrl?: string;
}

const metadata = await nango.getMetadata<MyMetadata>('<INTEGRATION-ID>', '<CONNECTION-ID>');

Connection tags

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.

Why use tags?

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

Recommended tags

Most apps start with these three tags:

{
  end_user_id: 'user_abc123',
  end_user_email: '[email protected]',
  organization_id: 'org_xyz789'
}

You can add any additional routing identifiers your application needs, such as workspace_id, project_id, or plan.

Set tags when creating a session

await nango.createConnectSession({
  tags: {
    end_user_id: '<END-USER-ID>',
    end_user_email: '<END-USER-EMAIL>',
    organization_id: '<ORGANIZATION-ID>'
  },
  allowed_integrations: ['<INTEGRATION-ID>']
});

Read tags from an auth webhook

Auth webhooks from Nango include the tags you set:

{
  "type": "auth",
  "operation": "creation",
  "success": true,
  "connectionId": "<CONNECTION-ID>",
  "tags": {
    "end_user_id": "<END-USER-ID>",
    "end_user_email": "<END-USER-EMAIL>",
    "organization_id": "<ORGANIZATION-ID>"
  }
}

Use these values to store connectionId alongside the corresponding entity in your database.

Filter connections by tags

const { connections } = await nango.listConnections({
  tags: {
    organization_id: 'org_xyz789'
  }
});

The filter uses an AND match: a connection must contain all provided tag key-value pairs to be returned.

Update tags on an existing connection

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:

TypeScript
cURL

await nango.patchConnection(
  {
    connectionId: '<CONNECTION-ID>',
    provider_config_key: '<INTEGRATION-ID>'
  },
  {
    tags: {
      end_user_id: '<END-USER-ID>',
      end_user_email: '<END-USER-EMAIL>',
      organization_id: '<ORGANIZATION-ID>',
      plan: 'enterprise'
    }
  }
);

curl --request PATCH \
  --url 'https://api.nango.dev/connections/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID>' \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": {
      "end_user_id": "<END-USER-ID>",
      "end_user_email": "<END-USER-EMAIL>",
      "organization_id": "<ORGANIZATION-ID>",
      "plan": "enterprise"
    }
  }'

Special tag keys

Two tag keys receive special treatment in the Nango dashboard:

Key	Effect
`end_user_display_name`	Shown in place of the connection ID in the connections list
`end_user_email`	Shown alongside the display name; the email domain is used to display the user’s company logo

Tag rules and limits

Keys are automatically lowercased (End_User_Email becomes end_user_email)
Keys must start with a letter and contain only alphanumerics, underscores, hyphens, periods, or slashes
Keys can be up to 64 characters long
Values must be non-empty strings up to 255 characters long
A maximum of 10 tag keys per connection are allowed
Avoid storing secrets or large free-form payloads in tags

Get Started

Auth

Functions

Use Cases

Platform

Connection management

Overview

List connections

Get a connection and its credentials

Delete a connection

Set and update metadata

Connection tags

Why use tags?

Recommended tags

Set tags when creating a session

Read tags from an auth webhook

Filter connections by tags

Update tags on an existing connection

Special tag keys

Tag rules and limits

Next steps

Implement auth

Connect UI

Build docs developers (and LLMs) love

Get Started

Auth

Functions

Use Cases

Platform

​Overview

​List connections

​Get a connection and its credentials

​Delete a connection

​Set and update metadata

​Connection tags

​Why use tags?

​Recommended tags

​Set tags when creating a session

​Read tags from an auth webhook

​Filter connections by tags

​Update tags on an existing connection

​Special tag keys

​Tag rules and limits

​Next steps

Implement auth

Connect UI

Build docs developers (and LLMs) love

Overview

List connections

Get a connection and its credentials

Delete a connection

Set and update metadata

Connection tags

Why use tags?

Recommended tags

Set tags when creating a session

Read tags from an auth webhook

Filter connections by tags

Update tags on an existing connection

Special tag keys

Tag rules and limits

Next steps