Node - Nango Docs

The backend SDK lets you interact with the Nango API. It is available on NPM as @nangohq/node.

Instantiate the backend SDK

Install it with your favorite package manager, e.g.:

npm i -S @nangohq/node

Instantiate the Nango class:

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

const nango = new Nango({ secretKey: '<SECRET-KEY>' });

Parameters

Show child attributes

config

object

required

Hide config

secretKey

string

required

Get your secret key in the environment settings of the Nango UI. THis key should never be shared.

host

string

Omitting the host points to Nango Cloud. For local development, use http://localhost:3003. Use your instance URL if self-hosting.

Rate limits

The Nango SDK is rate-limited to prevent abuse and ensure fair usage across all clients. The rate limit is enforced on a per-account basis, with a fixed window of time and a maximum number of requests allowed within that window. If a client exceeds the rate limit, the API will respond with a 429 Too Many Requests status code. In this case, the Retry-After header is included, indicating the number of seconds the client should wait before making another request to avoid being rate-limited. To handle rate limiting gracefully, clients should monitor for the 429 status code and honor the Retry-After header value provided in the response.

// Example:
try {
    const res = await nango.listIntegrations();
    ...
} catch(err) {
    if (err.response.status === 429) {
        const retryAfter = err.response.headers['retry-after'];
        // wait and retry
        ...
    }
    ...
}

Providers

List all providers

Returns a list of providers.

await nango.listProviders()

Example Response

Show child attributes

{
    "data": [
        {
            "name": "posthog",
            "categories": ["dev-tools"],
            "auth_mode": "API_KEY",
            "proxy": {
                "base_url": "https://api.posthog.com",
            },
            "docs": "https://docs.nango.dev/integrations/all/posthog"
        }
    ]
}

Get a provider

Returns a specific provider.

await nango.getProvider({ provider: <NAME> })

Example Response

Show child attributes

{
    "data": {
        "name": "posthog",
        "categories": ["dev-tools"],
        "auth_mode": "API_KEY",
        "proxy": {
            "base_url": "https://api.posthog.com",
        },
        "docs": "https://docs.nango.dev/integrations/all/posthog"
    }
}

Integrations

List all integrations

Returns a list of integrations.

await nango.listIntegrations()

Example Response

Show child attributes

{
    "configs": [
        {
            "unique_key": "slack-nango-community",
            "provider": "slack",
            "logo": "http://localhost:3003/images/template-logos/slack.svg",
            "created_at": "2023-10-16T08:45:26.241Z",
            "updated_at": "2023-10-16T08:45:26.241Z",
        },
        {
            "unique_key": "github-prod",
            "provider": "github",
            "logo": "http://localhost:3003/images/template-logos/github.svg",
            "created_at": "2023-10-16T08:45:26.241Z",
            "updated_at": "2023-10-16T08:45:26.241Z",
        },
    ]
}

Get an integration

Returns a specific integration.

await nango.getIntegration({ uniqueKey: <UNIQUE_KEY> });

// Deprecated
await nango.getIntegration(<INTEGRATION-ID>);

Parameters

Show child attributes

uniqueKey

string

required

The integration ID

include

array

Include sensitive data. Allowed values: webhook

Example Response

Show child attributes

{
    "data": {
        "unique_key": "slack-nango-community",
        "provider": "slack",
        "logo": "http://localhost:3003/images/template-logos/slack.svg",
        "created_at": "2023-10-16T08:45:26.241Z",
        "updated_at": "2023-10-16T08:45:26.241Z",
    }
}

Create an integration

Create a new integration.

await nango.createIntegration({ provider: <PROVIDER-ID>, unique_key: <UNIQUE_KEY>, [...] });

// Deprecated
await nango.createIntegration(<PROVIDER-ID>, <INTEGRATION-ID>);

Parameters

Show child attributes

provider

string

required

The ID of the API provider in Nango (cf. providers.yaml for a list of API provider IDs.)

unique_key

string

required

The integration ID.

display_name

string

The display name of this integration

credentials

Record<string, string>

The credentials to include depend on the specific integration that you want to create.

Example Response

Show child attributes

{
    "data": {
        "unique_key": "slack-nango-community",
        "provider": "slack",
        "logo": "http://localhost:3003/images/template-logos/slack.svg",
        "created_at": "2023-10-16T08:45:26.241Z",
        "updated_at": "2023-10-16T08:45:26.241Z",
    }
}

Update an integration

Patch an integration, all fields are optional.

await nango.updateIntegration({ uniqueKey: <UNIQUE_KEY> }, { [...body] });

// Deprecated
await nango.updateIntegration(<PROVIDER-ID>, <INTEGRATION-ID>);

Parameters

Show child attributes

unique_key

string

The integration ID.

display_name

string

The display name of this integration

credentials

Record<string, string>

The credentials to include depend on the specific integration that you want to create.

Example Response

Show child attributes

{
    "data": {
        "unique_key": "slack-nango-community",
        "provider": "slack",
        "logo": "http://localhost:3003/images/template-logos/slack.svg",
        "created_at": "2023-10-16T08:45:26.241Z",
        "updated_at": "2023-10-16T08:45:26.241Z",
    }
}

Delete an integration

Deletes a specific integration.

await nango.deleteIntegration(<UNIQUE_KEY>);

Parameters

Show child attributes

uniqueKey

string

required

The integration ID.

Example Response

Show child attributes

{
    "success": true
}

Connections

List connections

Returns a list of connections without credentials.

await nango.listConnections();

Parameters

Show child attributes

connectionId

string

Optional. Will exactly match a given connectionId. Can return multiple connections with the same ID across integrations.

string

Optional. Search connections. Will search in connection ID or end user profile.

queries

object

Hide queries

endUserId

string

Optional. Will exactly match a given end user ID.

endUserOrganizationId

string

Optional. Will exactly match a given end organization ID.

Example Response

Show child attributes

{
    "connections": [
        {
            "id": 1,
            "connection_id": "test-1",
            "provider": "slack",
            "provider_config_key": "slack-nango-community",
            "created": "2023-06-03T14:53:22.051Z",
            "metadata": null,
            "errors": []
        },
        {
            "id": 2,
            "connection_id": "test-2",
            "provider": "slack",
            "provider_config_key": "slack-nango-community",
            "created": "2023-06-03T15:00:14.945Z",
            "metadata": {
                "bot_id": "some-uuid"
            },
            "errors": [{ "type": "auth", "log_id": "VrnbtykXJFckCm3HP93t"}],
            "end_user": {
                "id": "your-internal-id",
                "email": "user@example.com",
                "organization": {
                    "id": "user-organization-id"
                }
            }
        }
    ]
}

Get a connection (with credentials)

Returns a specific connection with credentials.

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

The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth, etc.).If you do not want to deal with collecting & injecting credentials in requests for multiple authentication types, use the Proxy (step-by-step guide).

When you fetch the connection with this API endpoint, Nango will check if the access token has expired. If it has, it will refresh it.We recommend not caching tokens for longer than 5 minutes to ensure they are fresh.

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

connectionId

string

required

The connection ID.

forceRefresh

boolean

Defaults to false. If false, the token will only be refreshed if it expires within 15 minutes. If true, a token refresh attempt will happen on each request. This is only useful for testing and should not be done at high traffic.

refreshToken

boolean

Defaults to false. If false, the refresh token is not included in the response, otherwise it is. In production, it is not advised to return the refresh token, for security reasons, since only the access token is needed to sign requests.

refreshGithubAppJwtToken

boolean

Defaults to false. If true, this will refresh the JWT token for GitHub App / Github App OAuth connections

Example Response

Show child attributes

{
    "id": 18393,
    "created_at": "2023-03-08T09:43:03.725Z",
    "updated_at": "2023-03-08T09:43:03.725Z",
    "provider_config_key": "github",
    "connection_id": "1",
    "credentials": {
        "type": "OAUTH2",
        "access_token": "gho_tsXLG73f....",
        "refresh_token": "gho_fjofu84u9....",
        "expires_at": "2024-03-08T09:43:03.725Z",
        "raw": { // Raw token response from the OAuth provider: Contents vary!
            "access_token": "gho_tsXLG73f....",
            "refresh_token": "gho_fjofu84u9....",
            "token_type": "bearer",
            "scope": "public_repo,user"
        }
    },
    "connection_config": {
        "subdomain": "myshop",
        "realmId": "XXXXX",
        "instance_id": "YYYYYYY"
    },
    "metadata": {
        "myProperty": "yes",
        "filter": "closed=true"
    }
}

Patch a connection

Patch a connection.

await nango.patchConnection({
    connectionId: '<CONNECTION-ID>',
    providerConfigKey: '<INTEGRATION-ID>'
  },
  { ...body });

Parameters

Show child attributes

body

PatchPublicConnection['Body']

required

The body of the connection (see API Reference)

Example Response

Show child attributes

{
    "success": true
}

Get connection metadata

Returns a connection’s metadata.

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

If you know the structure of the metadata, you can specify a type;

interface CustomMetadata {
    anyKey: Record<string, string>;
}
const myTypedMetadata = await nango.getMetadata<CustomMetadata>('<INTEGRATION-ID>', '<CONNECTION-ID>');

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID of the connection.

connectionId

string

required

The connection ID.

Example Response

Show child attributes

{
    "custom_key1": "custom_value1"
}

Set connection metadata

Set custom metadata for the connection or connections (overrides existing metadata).

await nango.setMetadata('<INTEGRATION-ID>', 'CONNECTION-ID', { 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

# set an array of connection ids
await nango.setMetadata('<INTEGRATION-ID>', ['CONNECTION-ID', 'CONNECTION-ID-TWO'], { 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID of the connection.

connectionId

string | string[]

required

The connection ID or connection IDs.

metadata

Record<string, any>

required

The custom metadata to store in the connection.

Response

Show child attributes

{
    "connection_id": "<string | [string]>",
    "provider_config_key": "<string>",
    "metadata": {
        "CUSTOM_KEY1": "CUSTOM_VALUE1"
    }
}

Edit connection metadata

Edit custom metadata for the connection or connections. Only overrides specified properties, not the entire metadata.

await nango.updateMetadata('<INTEGRATION-ID>', 'CONNECTION-ID', { 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

# update an array of connection ids
await nango.updateMetadata('<INTEGRATION-ID>', ['CONNECTION-ID', 'CONNECTION-ID-TWO'], { 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID of the connection.

connectionId

string | string[]

required

The connection ID or connection IDs.

metadata

Record<string, any>

required

The custom metadata to store in the connection.

Response

Show child attributes

{
    "connection_id": "<string | [string]>",
    "provider_config_key": "<string>",
    "metadata": {
        "CUSTOM_KEY1": "CUSTOM_VALUE1"
    }
}

Delete a connection

Deletes a specific connection.

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

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID of the connection.

connectionId

string

required

The connection ID.

Response Empty response.

Integration functions

Get integration functions config

Return the configuration for all integration functions

const scriptsConfig = await nango.getScriptsConfig();

Example Response

Show child attributes

[
    {
        "providerConfigKey": "demo-github-integration",
        "syncs": [
            {
                "name": "github-issue-example",
                "type": "sync",
                "models": [
                    {
                        "name": "GithubIssue",
                        "fields": [
                            {
                                "name": "id",
                                "type": "integer"
                            },
                            {
                                "name": "owner",
                                "type": "string"
                            },
                            {
                                "name": "repo",
                                "type": "string"
                            },
                            {
                                "name": "issue_number",
                                "type": "number"
                            },
                            {
                                "name": "title",
                                "type": "string"
                            },
                            {
                                "name": "author",
                                "type": "string"
                            },
                            {
                                "name": "author_id",
                                "type": "string"
                            },
                            {
                                "name": "state",
                                "type": "string"
                            },
                            {
                                "name": "date_created",
                                "type": "date"
                            },
                            {
                                "name": "date_last_modified",
                                "type": "date"
                            },
                            {
                                "name": "body",
                                "type": "string"
                            }
                        ]
                    }
                ],
                "sync_type": "FULL",
                "runs": "every half hour",
                "track_deletes": false,
                "auto_start": false,
                "last_deployed": "2024-02-28T20:16:38.052Z",
                "is_public": false,
                "pre_built": false,
                "version": "4",
                "attributes": {},
                "input": {},
                "returns": [
                    "GithubIssue"
                ],
                "description": "Fetches the Github issues from all a user's repositories.\nDetails: full sync, doesn't track deletes, metadata is not required.\n",
                "scopes": [
                    "public_repo"
                ],
                "endpoints": [
                    {
                        "GET": "/github/issue-example"
                    }
                ],
                "nango_yaml_version": "v2",
                "webhookSubscriptions": []
            }
        ],
        "actions": [
            {
                "name": "fetch-issues",
                "type": "action",
                "models": [
                    {
                        "name": "GithubIssue",
                        "fields": [
                            {
                                "name": "id",
                                "type": "integer"
                            },
                            {
                                "name": "owner",
                                "type": "string"
                            },
                            {
                                "name": "repo",
                                "type": "string"
                            },
                            {
                                "name": "issue_number",
                                "type": "number"
                            },
                            {
                                "name": "title",
                                "type": "string"
                            },
                            {
                                "name": "author",
                                "type": "string"
                            },
                            {
                                "name": "author_id",
                                "type": "string"
                            },
                            {
                                "name": "state",
                                "type": "string"
                            },
                            {
                                "name": "date_created",
                                "type": "date"
                            },
                            {
                                "name": "date_last_modified",
                                "type": "date"
                            },
                            {
                                "name": "body",
                                "type": "string"
                            }
                        ]
                    }
                ],
                "runs": "",
                "is_public": false,
                "pre_built": false,
                "version": "4",
                "last_deployed": "2024-02-28T20:16:38.052Z",
                "attributes": {},
                "returns": [
                    "GithubIssue"
                ],
                "description": "",
                "scopes": [],
                "input": {},
                "endpoints": [
                    {
                        "GET": "/github/issues"
                    }
                ],
                "nango_yaml_version": "v2"
            }
        ],
        "postConnectionScripts": [],
        "provider": "github"
    }
]

You can also pass in an optional argument with the value of nango or openai. The default is nango

const scriptsConfig = await nango.getScriptsConfig('openai');

Show child attributes

{
  "data": [
    {
      "name": "calendars",
      "description": "Sync the user's calendar list.\nIncludes all calendars the user has access to.",
      "parameters": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "events",
      "description": "Sync calendar events from the primary calendar.\nIncludes events from the past month.",
      "parameters": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "cancel-event",
      "description": "Cancel/delete an event by searching for it.\n\nInput parameters:\n- title: The title of the event to cancel\n- date: The date of the event in ISO format\n- time: The time of the event in 24-hour format (HH:mm)\n- calendar: Calendar ID where to search for the event\n- id: Calendar identifier\n- summary: Calendar name/title\n- description: Calendar description\n- location: Calendar location\n- timeZone: Time zone of the calendar\n- backgroundColor: Calendar color in UI\n- foregroundColor: Text color in UI\n- selected: Whether the calendar is selected in UI\n- accessRole: User's access role for the calendar\n- primary: Whether this is the primary calendar",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Calendar identifier"
          },
          "summary": {
            "type": "string",
            "description": "Calendar name/title"
          },
          "description": {
            "type": "string",
            "description": "Calendar description"
          },
          "location": {
            "type": "string",
            "description": "Calendar location"
          },
          "timeZone": {
            "type": "string",
            "description": "Time zone of the calendar"
          },
          "backgroundColor": {
            "type": "string",
            "description": "Calendar color in UI"
          },
          "foregroundColor": {
            "type": "string",
            "description": "Text color in UI"
          },
          "selected": {
            "type": "boolean",
            "description": "Whether the calendar is selected in UI"
          },
          "accessRole": {
            "type": "string",
            "description": "User's access role for the calendar"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary calendar"
          },
          "title": {
            "type": "string",
            "description": "The title of the event to cancel"
          },
          "date": {
            "type": "string",
            "description": "The date of the event in ISO format"
          },
          "time": {
            "type": "string",
            "description": "The time of the event in 24-hour format (HH:mm)"
          },
          "calendar": {
            "type": "string",
            "description": "Calendar ID where to search for the event"
          }
        },
        "required": [
          "id",
          "summary"
        ]
      }
    },
    {
      "name": "create-event",
      "description": "Create a new calendar event.\n\nInput parameters:\n- summary: The title/summary of the event\n- description: A detailed description of the event\n- location: The location of the event\n- start: The start time of the event in ISO format\n- end: The end time of the event in ISO format\n- attendees: List of email addresses to invite\n- recurrence: List of recurrence rules in RRULE format\n- calendar: Calendar ID to create the event in\n- id: Calendar identifier\n- timeZone: Time zone of the calendar\n- backgroundColor: Calendar color in UI\n- foregroundColor: Text color in UI\n- selected: Whether the calendar is selected in UI\n- accessRole: User's access role for the calendar\n- primary: Whether this is the primary calendar",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Calendar identifier"
          },
          "summary": {
            "type": "string",
            "description": "The title/summary of the event"
          },
          "description": {
            "type": "string",
            "description": "A detailed description of the event"
          },
          "location": {
            "type": "string",
            "description": "The location of the event"
          },
          "timeZone": {
            "type": "string",
            "description": "Time zone of the calendar"
          },
          "backgroundColor": {
            "type": "string",
            "description": "Calendar color in UI"
          },
          "foregroundColor": {
            "type": "string",
            "description": "Text color in UI"
          },
          "selected": {
            "type": "boolean",
            "description": "Whether the calendar is selected in UI"
          },
          "accessRole": {
            "type": "string",
            "description": "User's access role for the calendar"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary calendar"
          },
          "start": {
            "type": "string",
            "description": "The start time of the event in ISO format"
          },
          "end": {
            "type": "string",
            "description": "The end time of the event in ISO format"
          },
          "attendees": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of email addresses to invite"
          },
          "recurrence": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of recurrence rules in RRULE format"
          },
          "calendar": {
            "type": "string",
            "description": "Calendar ID to create the event in"
          }
        },
        "required": [
          "id",
          "summary",
          "start",
          "end"
        ]
      }
    },
    {
      "name": "move-event",
      "description": "Move an event to a different time or calendar.\n\nInput parameters:\n- eventId: The ID of the event to move\n- title: The title of the event to move\n- sourceStart: The current start time of the event\n- start: The new start time for the event in ISO format\n- end: The new end time for the event in ISO format\n- calendar: Calendar ID to move the event to\n- id: Calendar identifier\n- summary: Calendar name/title\n- description: Calendar description\n- location: Calendar location\n- timeZone: Time zone of the calendar\n- backgroundColor: Calendar color in UI\n- foregroundColor: Text color in UI\n- selected: Whether the calendar is selected in UI\n- accessRole: User's access role for the calendar\n- primary: Whether this is the primary calendar",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Calendar identifier"
          },
          "summary": {
            "type": "string",
            "description": "Calendar name/title"
          },
          "description": {
            "type": "string",
            "description": "Calendar description"
          },
          "location": {
            "type": "string",
            "description": "Calendar location"
          },
          "timeZone": {
            "type": "string",
            "description": "Time zone of the calendar"
          },
          "backgroundColor": {
            "type": "string",
            "description": "Calendar color in UI"
          },
          "foregroundColor": {
            "type": "string",
            "description": "Text color in UI"
          },
          "selected": {
            "type": "boolean",
            "description": "Whether the calendar is selected in UI"
          },
          "accessRole": {
            "type": "string",
            "description": "User's access role for the calendar"
          },
          "primary": {
            "type": "boolean",
            "description": "Whether this is the primary calendar"
          },
          "eventId": {
            "type": "string",
            "description": "The ID of the event to move"
          },
          "title": {
            "type": "string",
            "description": "The title of the event to move"
          },
          "sourceStart": {
            "type": "string",
            "description": "The current start time of the event"
          },
          "start": {
            "type": "string",
            "description": "The new start time for the event in ISO format"
          },
          "end": {
            "type": "string",
            "description": "The new end time for the event in ISO format"
          },
          "calendar": {
            "type": "string",
            "description": "Calendar ID to move the event to"
          }
        },
        "required": [
          "id",
          "summary",
          "start",
          "end"
        ]
      }
    },
    {
      "name": "whoami",
      "description": "Get information about the authenticated user.\n\nNo input parameters.",
      "parameters": {
        "type": "object",
        "properties": {},
        "required": []
      }
    },
    {
      "name": "invite-user-to-repository",
      "description": "Invite a user to a GitHub repository.\n\nInput parameters:\n- owner: The owner (user or organization) of the repository\n- repo: The name of the repository to invite the user to\n- username: The GitHub username of the user to invite\n- permission: The permission level to grant (\"pull\", \"push\", \"admin\", \"maintain\", \"triage\")",
      "parameters": {
        "type": "object",
        "properties": {
          "owner": {
            "type": "string",
            "description": "The owner (user or organization) of the repository"
          },
          "repo": {
            "type": "string",
            "description": "The name of the repository to invite the user to"
          },
          "username": {
            "type": "string",
            "description": "The GitHub username of the user to invite"
          },
          "permission": {
            "type": "string",
            "description": "The permission level to grant (\"pull\", \"push\", \"admin\", \"maintain\", \"triage\")"
          }
        },
        "required": [
          "owner",
          "repo",
          "username"
        ]
      }
    }
  ]
}

Syncs

Get records

Returns the synced data.

import type { ModelName } from '<path-to-nango-integrations>/models'

const records = await nango.listRecords<ModelName>({
    providerConfigKey: '<INTEGRATION-ID>',
    connectionId: '<CONNECTION-ID>',
    model: '<MODEL-NAME>'
});

Parameters

Show child attributes

config

object

required

Hide config

providerConfigKey

string

required

The integration ID.

connectionId

string

required

The connection ID.

model

string

required

The name of the model of the data you want to retrieve.

variant

string

The variant of the model to fetch. When omitted, the default base variant is used.

cursor

string

Each record from this endpoint comes with a synchronization cursor in _nango_metadata.cursor.Save the last fetched record’s cursor to track how far you’ve synced.By providing the cursor to this method, you’ll continue syncing from where you left off, receiving only post-cursor changes.This same cursor is used to paginate through the results of this endpoint.

limit

number

The maximum number of records to return. Defaults to 100.

filter

string

Filter to only show results that have been added or updated or deleted.Available options: added, updated, deleted

modifiedAfter

string

Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.

ids

string[]

An array of string containing a list of your records IDs. The list will be filtered to include only the records with a matching ID.

delta

string

DEPRECATED (use modifiedAfter) Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.

Example Response

This endpoint returns a list of records, ordered by modification date ascending. If some records are updated while you paginate through this endpoint, you might see these records multiple times.

Show child attributes

{
    records:
        [
            {
                id: 123,
                ..., // Fields as specified in the model you queried
                _nango_metadata: {
                    deleted_at: null,
                    last_action: 'ADDED',
                    first_seen_at: '2023-09-18T15:20:35.941305+00:00',
                    last_modified_at: '2023-09-18T15:20:35.941305+00:00',
                    cursor: 'MjAyNC0wMi0yNlQwMzowMDozOS42MjMzODgtMDU6MDB8fGVlMDYwM2E1LTEwNDktNDA4Zi05YTEwLTJjNzVmNDkwODNjYQ=='
                }
            },
            ...
        ],
    next_cursor: "Y3JlYXRlZF9hdF4yMDIzLTExLTE3VDExOjQ3OjE0LjQ0NyswMjowMHxpZF4xYTE2MTYwMS0yMzk5LTQ4MzYtYWFiMi1mNjk1ZWI2YTZhYzI"
}

Trigger sync(s)

Triggers an additional, one-off execution of specified sync(s) for a given connection or all applicable connections if no connection is specified.

// Simple usage with sync names
const result = await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>', 'incremental');

// Using variants
const resultWithVariants = await nango.triggerSync('<INTEGRATION-ID>', [
  { name: 'SYNC_NAME1', variant: 'VARIANT_A' },
  'SYNC_NAME2' // Uses default base variant
], '<CONNECTION_ID>', 'incremental');

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

syncs

Array<string | {name: string, variant: string}>

required

The name of the syncs to trigger. If the array is empty, all syncs are triggered. Each sync can be specified as either:

A string: the sync name (uses the default base variant)
An object: with name and variant properties to target a specific sync variant

connectionId

string

The connection ID. If omitted, the sync will trigger for all relevant connections.

sync_mode

'incremental' | 'full_refresh' | 'full_refresh_and_clear_cache'

The mode in which to trigger the syncs.

incremental: Triggers a new sync job while preserving the “lastSyncDate”.
full_refresh: Resets the “lastSyncDate” associated with the sync before triggering a new sync job.
full_refresh_and_clear_cache: Resets the “lastSyncDate” and deletes all records associated with the sync before triggering a new sync job.

Response Empty response.

Start schedule for sync(s)

Starts the schedule of specified sync(s) for a given connection or all applicable connections if no connection is specified. Upon starting the schedule, the sync will execute immediately and then continue to run at the specified frequency. If the schedule was already started, this will have no effect.

// Simple usage with sync names
await nango.startSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>');

// Using variants
await nango.startSync('<INTEGRATION-ID>', [
  { name: 'SYNC_NAME1', variant: 'VARIANT_A' },
  'SYNC_NAME2' // Uses default base variant
], '<CONNECTION_ID>');

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

syncs

Array<string | {name: string, variant: string}>

required

The name of the syncs that should be triggered. Each sync can be specified as either:

A string: the sync name (uses the default base variant)
An object: with name and variant properties to target a specific sync variant

connectionId

string

The connection ID. If omitted, the sync will trigger for all relevant connections.

Response Empty response.

Pause schedule for sync(s)

Pauses the schedule of specified sync(s) for a given connection or all applicable connections if no connection is specified.

// Simple usage with sync names
await nango.pauseSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>');

// Using variants
await nango.pauseSync('<INTEGRATION-ID>', [
  { name: 'SYNC_NAME1', variant: 'VARIANT_A' },
  'SYNC_NAME2' // Uses default base variant
], '<CONNECTION_ID>');

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

syncs

Array<string | {name: string, variant: string}>

required

The name of the syncs that should be paused. Each sync can be specified as either:

A string: the sync name (uses the default base variant)
An object: with name and variant properties to target a specific sync variant

connectionId

string

The connection ID. If omitted, the sync will pause for all relevant connections.

Response Empty response.

Sync status

Get the status of specified sync(s) for a given connection or all applicable connections if no connection is specified.

// Simple usage with sync names
await nango.syncStatus('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>');

// Using variants
await nango.syncStatus('<INTEGRATION-ID>', [
  { name: 'SYNC_NAME1', variant: 'VARIANT_A' },
  'SYNC_NAME2' // Uses default base variant
], '<CONNECTION_ID>');

// Get all syncs
await nango.syncStatus('<INTEGRATION-ID>', '*', '<CONNECTION_ID>');

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

syncs

string | Array<string | {name: string, variant: string}>

required

Either ”*” to return all syncs, or an array of syncs to fetch status for. When using an array, each sync can be specified as either:

A string: the sync name (uses the default base variant)
An object: with name and variant properties to target a specific sync variant

connectionId

string

The connection ID. If omitted, all connections will be surfaced.

Response

Show child attributes

{
    "syncs": [
        {
            "id": "<string>",
            "connection_id": "<string>",
            "name": "<string>",
            "variant": "<string>",
            "status": "RUNNING",
            "type": "INCREMENTAL",
            "finishedAt": "<string>",
            "nextScheduledSyncAt": "<string>",
            "frequency": "<string>",
            "latestResult": {
                "<string>": {
                    "added": <number>,
                    "updated": <number>,
                    "deleted": <number>,
                }
            },
            "recordCount": {
                "<string>": <number>
                ...
            }
        }
    ]
}

Override sync connection frequency

Override a sync’s default frequency for a specific connection, or revert to the default frequency.

// For base variant
await nango.updateSyncConnectionFrequency('<INTEGRATION-ID>', 'SYNC_NAME', '<CONNECTION_ID>', '<FREQUENCY>');

// For a specific variant
await nango.updateSyncConnectionFrequency('<INTEGRATION-ID>', { name: 'SYNC_NAME', variant: 'VARIANT_NAME' }, '<CONNECTION_ID>', '<FREQUENCY>');

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

sync

string | {name: string, variant: string}

required

The sync to update. Can be specified as either:

A string: the sync name (uses the default base variant)
An object: with name and variant properties to target a specific sync variant

connectionId

string

required

The connection ID.

frequency

string

required

The frequency you want to set (ex: ‘every hour’). Set to null to revert to the default frequency. Uses the https://github.com/vercel/ms notations. Min frequency: 5 minutes.

Response

Show child attributes

{
    "frequency": "<string>"
}

Create sync variant

Creates a new sync variant for a specific connection. Sync variants allow you to run multiple instances of the same sync with different configurations.

await nango.createSyncVariant({
  provider_config_key: '<INTEGRATION-ID>',
  connection_id: '<CONNECTION_ID>',
  name: 'SYNC_NAME',
  variant: 'VARIANT_NAME'
});

Parameters

Show child attributes

props

object

required

Hide props

provider_config_key

string

required

The integration ID.

connection_id

string

required

The connection ID.

name

string

required

The name of the sync.

variant

string

required

The name of the variant to create. Cannot be “base” (protected name).

Example Response

Show child attributes

{
    "id": "12345",
    "name": "SYNC_NAME",
    "variant": "VARIANT_NAME"
}

Delete sync variant

Deletes a sync variant for a specific connection.

await nango.deleteSyncVariant({
  provider_config_key: '<INTEGRATION-ID>',
  connection_id: '<CONNECTION_ID>',
  name: 'SYNC_NAME',
  variant: 'VARIANT_NAME'
});

Parameters

Show child attributes

props

object

required

Hide props

provider_config_key

string

required

The integration ID.

connection_id

string

required

The connection ID.

name

string

required

The name of the sync.

variant

string

required

The name of the variant to delete. Cannot be “base” (protected name).

Example Response

Show child attributes

{
    "success": true
}

Get environment variables

Retrieve the environment variables as added in the Nango dashboard.

await nango.getEnvironmentVariables();

Parameters No parameters. Response

Show child attributes

[
    {
        "name": "MY_SECRET_KEY",
        "value": "SK_373892NSHFNCOWFO..."
    }
]

Actions

Trigger an action

Triggers an action for a connection.

await nango.triggerAction('<INTEGRATION-ID>', '<CONNECTION_ID>', '<ACTION-NAME>', { 'custom_key1': 'custom_value1' });

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

connectionId

string

required

The connection ID.

actionName

string

required

The name of the action to trigger.

input

unknown

The necessary input for your action’s exec function.

Response

Show child attributes

{
    "your-properties": "The data returned by the action"
}

The output of an action cannot exceed 10MB.

Trigger an action asynchronously

Triggers an action asynchronously for a connection. This allows you to start an action and retrieve the results later.

const { id, statusUrl } = await nango.triggerActionAsync('<INTEGRATION-ID>', '<CONNECTION_ID>', '<ACTION-NAME>', { 'custom_key1': 'custom_value1' });

Parameters

Show child attributes

providerConfigKey

string

required

The integration ID.

connectionId

string

required

The connection ID.

actionName

string

required

The name of the action to trigger.

input

unknown

The necessary input for your action’s exec function.

Response

Show child attributes

{
    "id": "action_123456",
    "statusUrl": "/action/action_123456"
}

Get async action result

Retrieves the result of an asynchronous action.

// Using the id
const result = await nango.getAsyncActionResult({ id: 'action_123456' });

// OR using the statusUrl
const result = await nango.getAsyncActionResult({ statusUrl: '/action/action_123456' });

Parameters

Show child attributes

props

object

required

Hide props

string

The ID of the action to retrieve the result for.

statusUrl

string

The URL where the result can be retrieved.

Response

Show child attributes

{
    "your-properties": "The data returned by the action"
}

Proxy

Makes an HTTP request using the proxy:

const config = {
    endpoint: '/some-endpoint',
    providerConfigKey: '<INTEGRATION-ID>',
    connectionId: '<CONNECTION-ID>'
};

await nango.get(config); // GET request
await nango.post(config); // POST request
await nango.put(config); // PUT request
await nango.patch(config); // PATCH request
await nango.delete(config); // DELETE request

Parameters

Show child attributes

config

object

required

Hide config

endpoint

string

required

The endpoint of the request.

providerConfigKey

string

required

The integration ID (for credential injection).

connectionId

string

required

The connection ID (for credential injection).

headers

Record<string, string>

The headers of the request.

params

Record<string, string | number>

The query parameters of the request.

data

unknown

The body of the request.

retries

number

The number of retries in case of failure (with exponential back-off). Optional, default 0.

retryOn

number[]

Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED

baseUrlOverride

string

The API base URL. Can be omitted if the base URL is configured for this API in the providers.yaml.

decompress

boolean

Override the decompress option when making requests. Optional, defaults to false

responseType

The type of the response.

Response

Show child attributes

The response from the external API is passed back to you exactly as Nango gets it:

response code
response headers
response body

Connect

Create a connect session

Create a connect session for a given end user

const { data } = await nango.createConnectSession({
  end_user: {
    id: '<END-USER-ID>',
    email: '<END-USER-EMAIL>',
    display_name: '<END-USER-NAME>'
  },
  organization: {
    id: '<ORGANIZATION-ID>',
    display_name: '<ORGANIZATION-NAME>'
  },
  allowed_integrations: ['<INTEGRATION-ID-1>', '<INTEGRATION-ID-2>'],
  integrations_config_defaults: {
    <INTEGRATION-ID-1>: {
      connection_config: {
        <CONFIG-KEY>: '<VALUE>'
      }
    }
  }
});

Parameters

Show child attributes

end_user

object

required

Hide end_user

string

required

The unique identifier for the end user.

string

The email address of the end user.

display_name

string

The display name of the end user.

organization

object

Hide organization

string

required

The unique identifier for the organization.

display_name

string

The display name of the organization.

allowed_integrations

string[]

An array of integration IDs that are allowed for this session.

integrations_config_defaults

object

Default configuration for specific integrations.

Returns

Show child attributes

{
    "data": {
        "token": "nango_connect_session_4603dbca8a588315ba69b5bfddde52e72d312dc2d2870bd5e45da6357333601c",
        "expires_at": "2024-09-27T19:49:51.449Z"
    }
}

Create a reconnect session

Create a reconnect session for a given connection_id. Optionally, you can set end_user and organization to update those attributes of the connection. Use this method when a user needs to input new credentials or to manually refresh token.

This method is only compatible with connection_id created with a session token.

const { data } = await nango.createReconnectSession({
  // Required
  connection_id: '<CONNECTION-ID>'
  integration_id: '<INTEGRATION-ID>',

  // Optional
  end_user: {
    id: '<END-USER-ID>',
    email: '<END-USER-EMAIL>',
    display_name: '<END-USER-NAME>'
  },
  organization: {
    id: '<ORGANIZATION-ID>',
    display_name: '<ORGANIZATION-NAME>'
  },
  integrations_config_defaults: {
    <INTEGRATION-ID-1>: {
      connection_config: {
        <CONFIG-KEY>: '<VALUE>'
      }
    }
  }
});

Parameters

Show child attributes

connection_id

string

required

The unique identifier for the connection.

integration_id

string

required

The unique identifier for the integration.

end_user

object

Show end_user

string

required

The unique identifier for the end user.

string

The email address of the end user.

display_name

string

The display name of the end user.

organization

object

Show organization

string

required

The unique identifier for the organization.

display_name

string

The display name of the organization.

integrations_config_defaults

object

Default configuration for specific integrations.

Returns

Show child attributes

{
    "data": {
        "token": "nango_connect_session_4603dbca8a588315ba69b5bfddde52e72d312dc2d2870bd5e45da6357333601c",
        "expires_at": "2024-09-27T19:49:51.449Z"
    }
}

Webhooks from Nango

Verify Webhook Signature

Asserts that a Webhook is coming from Nango’s backend.

async (req, res) => {
    const signature = req.headers['x-nango-signature'];
    const isValid = nango.verifyWebhookSignature(signature, req.body);
}

Questions, problems, feedback? Please reach out in the Slack community.

Reference

Use Integrations - Reference

Build Integrations - Reference

​Instantiate the backend SDK

​Rate limits

​Providers

​List all providers

​Get a provider

​Integrations

​List all integrations

​Get an integration

​Create an integration

​Update an integration

​Delete an integration

​Connections

​List connections

​Get a connection (with credentials)

​Patch a connection

​Get connection metadata

​Set connection metadata

​Edit connection metadata

​Delete a connection

​Integration functions

​Get integration functions config

​Syncs

​Get records

​Trigger sync(s)

​Start schedule for sync(s)

​Pause schedule for sync(s)

​Sync status

​Override sync connection frequency

​Create sync variant

​Delete sync variant

​Get environment variables

​Actions

​Trigger an action

​Trigger an action asynchronously

​Get async action result

​Proxy

​Connect

​Create a connect session

​Create a reconnect session

​Webhooks from Nango

​Verify Webhook Signature

Instantiate the backend SDK

Rate limits

Providers

List all providers

Get a provider

Integrations

List all integrations

Get an integration

Create an integration

Update an integration

Delete an integration

Connections

List connections

Get a connection (with credentials)

Patch a connection

Get connection metadata

Set connection metadata

Edit connection metadata

Delete a connection

Integration functions

Get integration functions config

Syncs

Get records

Trigger sync(s)

Start schedule for sync(s)

Pause schedule for sync(s)

Sync status

Override sync connection frequency

Create sync variant

Delete sync variant

Get environment variables

Actions

Trigger an action

Trigger an action asynchronously

Get async action result

Proxy

Connect

Create a connect session

Create a reconnect session

Webhooks from Nango

Verify Webhook Signature