Connections API

A connection represents one end user’s authenticated session with an external provider through an integration. It stores the user’s credentials (OAuth tokens, API keys, etc.) securely and refreshes them automatically when needed. Every connection belongs to an integration and is identified by a connection_id you assign (typically your internal user ID) plus the provider_config_key of its integration.

All API requests require a secret key passed as a Bearer token. You can find your secret key in the Settings section of the Nango dashboard.

List connections

curl --request GET \
  --url 'https://api.nango.dev/connections?connectionId=user-123&limit=20' \
  --header 'Authorization: Bearer <SECRET_KEY>'

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

// Filter by connection ID
const result = await nango.listConnections('user-123');

// Filter using object syntax
const result = await nango.listConnections({
  connectionId: 'user-123',
  integrationId: 'slack-production',
  limit: 20
});

GET /connections Returns a paginated list of connections. You can filter by connection ID, end user, integration, and custom tags.

Query parameters

string

Exact match on the connection ID. Can return multiple connections across different integrations if the same ID is used.

string

Filter by integration unique key (e.g. slack-production). Accepts a comma-separated list for multiple integrations.

string

Filter connections belonging to a specific end user ID.

string

Filter connections belonging to end users in a specific organization.

string

Search in connection ID or end user profile (name, email).

number

default:"100"

Maximum number of connections to return per page.

number

default:"0"

Page number for pagination (zero-indexed).

Response

ApiPublicConnection[]

Hide properties

number

required

Internal numeric ID of the connection.

string

required

Your identifier for this connection (typically an end user ID).

string

required

The unique key of the integration this connection belongs to.

string

required

The provider slug (e.g. slack, github).

string

required

ISO 8601 timestamp of when the connection was created.

object | null

Custom metadata you have attached to this connection.

object

Key-value tags attached to this connection (e.g. end_user_id, end_user_email, organization_id).

array

Active errors on this connection (e.g. expired credentials). Each error has type and log_id.

object | null

The end user associated with this connection, if set.

Example response

{
  "connections": [
    {
      "id": 1,
      "connection_id": "user-123",
      "provider": "slack",
      "provider_config_key": "slack-production",
      "created": "2023-06-03T14:53:22.051Z",
      "metadata": null,
      "tags": {
        "end_user_id": "user-123",
        "end_user_email": "alice@example.com",
        "organization_id": "org-456"
      },
      "errors": [],
      "end_user": {
        "id": "user-123",
        "email": "alice@example.com",
        "display_name": "Alice"
      }
    },
    {
      "id": 2,
      "connection_id": "user-456",
      "provider": "slack",
      "provider_config_key": "slack-production",
      "created": "2023-06-03T15:00:14.945Z",
      "metadata": {
        "bot_id": "B01234ABCDE"
      },
      "tags": {
        "end_user_id": "user-456",
        "end_user_email": "bob@example.com"
      },
      "errors": [{ "type": "auth", "log_id": "VrnbtykXJFckCm3HP93t" }],
      "end_user": null
    }
  ]
}

Get a connection

curl --request GET \
  --url 'https://api.nango.dev/connections/user-123?provider_config_key=slack-production' \
  --header 'Authorization: Bearer <SECRET_KEY>'

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

// Get the full connection object (including credentials)
const connection = await nango.getConnection('slack-production', 'user-123');

// Get just the access token
const token = await nango.getToken('slack-production', 'user-123');

// Force a token refresh before returning
const connection = await nango.getConnection(
  'slack-production',
  'user-123',
  true // forceRefresh
);

GET /connections/:connectionId Returns a single connection including its live credentials. Nango automatically refreshes expired access tokens before returning the response.

Always fetch credentials just before you use them. Nango refreshes tokens on this call, so you always get a valid, non-expired credential.

The shape of the credentials field depends on the provider’s auth type (OAuth 2, OAuth 1, API key, Basic auth, etc.). Use the Proxy if you want Nango to inject credentials into requests for you.

Path parameters

string

required

The connection ID to retrieve.

Query parameters

string

required

The unique key of the integration this connection belongs to. Required because the same connection_id can exist across multiple integrations.

boolean

default:"false"

Force a new token fetch from the provider even if the current token is still valid.

boolean

default:"false"

Include the refresh token in the response (OAuth 2 only).

boolean

default:"false"

Refresh the JWT token for GitHub App or GitHub App OAuth connections.

Response

number

required

Internal numeric ID of the connection.

string

required

Your identifier for this connection.

string

required

The integration’s unique key.

string

required

The provider slug (e.g. slack).

object

Provider-specific connection configuration set during auth (e.g. subdomain, instance URL).

object | null

Custom metadata you have attached to this connection.

object

Key-value tags attached to this connection.

object

required

The live credentials for this connection. Shape depends on auth type.

Show OAuth 2

string

OAUTH2

string

The current access token.

string

Present only when refresh_token=true is passed.

string

ISO 8601 expiry time of the access token.

object

The full raw token response from the provider.

Show OAuth 1

string

OAUTH1

string

The OAuth 1.0a access token.

string

The OAuth 1.0a token secret.

object

The full raw token response from the provider.

Show API Key

string

API_KEY

string

The API key.

Show Basic Auth

string

BASIC

string

The username.

string

The password.

array

Active errors on this connection.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

Example response (OAuth 2)

{
  "id": 1,
  "connection_id": "user-123",
  "provider_config_key": "slack-production",
  "provider": "slack",
  "connection_config": {},
  "metadata": { "workspace_id": "T01234ABCDE" },
  "tags": {
    "end_user_id": "user-123",
    "end_user_email": "alice@example.com"
  },
  "credentials": {
    "type": "OAUTH2",
    "access_token": "xoxp-1234567890-abcdefghij",
    "expires_at": "2024-01-15T11:30:00.000Z",
    "raw": {
      "ok": true,
      "access_token": "xoxp-1234567890-abcdefghij",
      "token_type": "Bearer",
      "scope": "channels:read,chat:write"
    }
  },
  "errors": [],
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T11:29:58.000Z"
}

Import a connection

curl --request POST \
  --url https://api.nango.dev/connections \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "connection_id": "user-123",
    "provider_config_key": "github-prod",
    "credentials": {
      "type": "OAUTH2",
      "access_token": "gho_existingtoken",
      "refresh_token": "ghr_existingrefreshtoken",
      "expires_at": "2024-12-31T23:59:59.000Z"
    },
    "metadata": {
      "github_username": "alice"
    }
  }'

// Use the REST API directly — the Node SDK does not expose this method.
// The SDK's createConnection method is deprecated.

POST /connections Imports existing credentials into Nango without going through an OAuth flow. Use this for bulk migrations when onboarding to Nango.

This endpoint is intended for one-off bulk imports of existing tokens. For new connections, use the Connect UI or the frontend SDK to run the OAuth flow.

Request body

string

required

The unique key of the integration to create the connection under.

string

Your identifier for this connection. If omitted, Nango generates one.

object

required

The credentials to import. The required fields depend on the provider’s auth type.

Show OAuth 2

string

required

OAUTH2

string

required

Existing access token.

string

Existing refresh token (recommended).

string

ISO 8601 expiry of the access token.

Show OAuth 1

string

required

OAUTH1

string

required

OAuth 1.0a access token.

string

required

OAuth 1.0a token secret.

Show API Key

string

required

API_KEY

string

required

The API key to import.

Show Basic Auth

string

required

BASIC

string

required

Username.

string

required

Password.

Show No auth (NONE)

string

required

NONE

object

Custom metadata to attach to the connection.

object

Provider-specific configuration (e.g. subdomain, instance_url).

object

End user to associate with this connection.

Show properties

string

required

Your internal user ID.

string

User’s email address.

string

User’s display name.

object

Key-value tags to attach to the connection (e.g. { "plan": "enterprise" }).

Response

Returns the created connection object including its credentials. See Get a connection for the full response shape.

Update a connection

curl --request PATCH \
  --url 'https://api.nango.dev/connections/user-123?provider_config_key=slack-production' \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "end_user": {
      "id": "user-123",
      "email": "alice-new@example.com",
      "display_name": "Alice Smith"
    },
    "tags": {
      "plan": "enterprise",
      "organization_id": "org-456"
    }
  }'

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

await nango.patchConnection(
  { connectionId: 'user-123', provider_config_key: 'slack-production' },
  {
    end_user: {
      id: 'user-123',
      email: 'alice-new@example.com',
      display_name: 'Alice Smith'
    },
    tags: { plan: 'enterprise', organization_id: 'org-456' }
  }
);

PATCH /connections/:connectionId Updates the end user profile or tags on a connection. Does not modify credentials.

Path parameters

string

required

The connection ID to update.

Query parameters

string

required

The unique key of the integration this connection belongs to.

Request body

object

Updated end user information to associate with this connection.

Show properties

string

required

Your internal user ID.

string

Updated email address.

string

Updated display name.

object

Key-value tags to set on the connection. This replaces the existing tag set.

Response

Example response

{
  "success": true
}

Delete a connection

curl --request DELETE \
  --url 'https://api.nango.dev/connections/user-123?provider_config_key=slack-production' \
  --header 'Authorization: Bearer <SECRET_KEY>'

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

await nango.deleteConnection('slack-production', 'user-123');

DELETE /connections/:connectionId Permanently deletes a connection and its stored credentials.

Path parameters

string

required

The connection ID to delete.

Query parameters

string

required

The unique key of the integration this connection belongs to.

Response

Example response

{
  "success": true
}

Set connection metadata

curl --request POST \
  --url https://api.nango.dev/connections/metadata \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "connection_id": "user-123",
    "provider_config_key": "slack-production",
    "metadata": {
      "workspace_id": "T01234ABCDE",
      "bot_id": "B09876ZYXWV"
    }
  }'

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

// Set metadata on a single connection
await nango.setMetadata('slack-production', 'user-123', {
  workspace_id: 'T01234ABCDE',
  bot_id: 'B09876ZYXWV'
});

// Set the same metadata on multiple connections
await nango.setMetadata('slack-production', ['user-123', 'user-456'], {
  workspace_id: 'T01234ABCDE'
});

POST /connections/metadata Replaces the metadata on one or more connections entirely. Existing metadata is overwritten.

This replaces the entire metadata object. Use Update metadata (PATCH) to merge changes without overwriting existing keys.

Request body

string | string[]

required

The connection ID to update, or an array of connection IDs to update in bulk.

string

required

The unique key of the integration the connection(s) belong to.

object

required

The new metadata to set. Must be a JSON object. All existing metadata keys are replaced.

Response

Returns the body you sent as confirmation.

Example response

{
  "connection_id": "user-123",
  "provider_config_key": "slack-production",
  "metadata": {
    "workspace_id": "T01234ABCDE",
    "bot_id": "B09876ZYXWV"
  }
}

Update connection metadata

curl --request PATCH \
  --url https://api.nango.dev/connections/metadata \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "connection_id": "user-123",
    "provider_config_key": "slack-production",
    "metadata": {
      "bot_id": "B-NEW-VALUE"
    }
  }'

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

// Update specific metadata keys without touching others
await nango.updateMetadata('slack-production', 'user-123', {
  bot_id: 'B-NEW-VALUE'
});

PATCH /connections/metadata Merges the provided metadata into the connection’s existing metadata. Only the keys you provide are updated; all other keys remain unchanged.

Request body

string | string[]

required

The connection ID to update, or an array of connection IDs to update in bulk.

string

required

The unique key of the integration the connection(s) belong to.

object

required

The metadata keys to update. Only these keys are changed; existing keys not included here are preserved.

Response

Returns the body you sent as confirmation.

Example response

{
  "connection_id": "user-123",
  "provider_config_key": "slack-production",
  "metadata": {
    "bot_id": "B-NEW-VALUE"
  }
}

Reading metadata

To read a connection’s metadata, fetch the connection using Get a connection. The metadata field is included in the response.

Node SDK

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

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const metadata = await nango.getMetadata('slack-production', 'user-123');
// Returns: { workspace_id: "T01234ABCDE", bot_id: "B09876ZYXWV" }

Overview

Integrations & Connections

Functions & Proxy

SDKs

Connections API

List connections

Query parameters

Response

Get a connection

Path parameters

Query parameters

Response

Import a connection

Request body

Response

Update a connection

Path parameters

Query parameters

Request body

Response

Delete a connection

Path parameters

Query parameters

Response

Set connection metadata

Request body

Response

Update connection metadata

Request body

Response

Reading metadata

​List connections

​Query parameters

​Response

​Get a connection

​Path parameters

​Query parameters

​Response

​Import a connection

​Request body

​Response

​Update a connection

​Path parameters

​Query parameters

​Request body

​Response

​Delete a connection

​Path parameters

​Query parameters

​Response

​Set connection metadata

​Request body

​Response

​Update connection metadata

​Request body

​Response

​Reading metadata

List connections

Query parameters

Response

Get a connection

Path parameters

Query parameters

Response

Import a connection

Request body

Response

Update a connection

Path parameters

Query parameters

Request body

Response

Delete a connection

Path parameters

Query parameters

Response

Set connection metadata

Request body

Response

Update connection metadata

Request body

Response

Reading metadata