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: 'user@example.com',
  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

​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

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