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

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

{
    "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

{
    "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

{
    "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

Example Response

{
    "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-ID>, <INTEGRATION-ID>);

Parameters

Example Response

Update an integration

Edits an integration (only for OAuth APIs).

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

Parameters

Example Response

Delete an integration

Deletes a specific integration.

await nango.deleteIntegration(<INTEGRATION-ID>);

Parameters

Example Response

Connections

List connections

Returns a list of connections without credentials.

await nango.listConnections();

Parameters

Example Response

{
    "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"}]
        }
    ]
}

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

Example Response

{
    "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"
    },
    "account_id": 0,
    "metadata": {
        "myProperty": "yes",
        "filter": "closed=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

Example Response

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

Response

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

Response

Delete a connection

Deletes a specific connection.

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

Parameters

Response

Empty response.

Integration scripts

Get integration scripts config

Return the configuration for all integration scripts

const scriptsConfig = await nango.getScriptsConfig();

Example Response

[
    {
        "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"
    }
]

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

nango.getRecords() is deprecated and will be removed in future releases as it does not support efficient pagination. Please use nango.listRecords() detailed below.

Parameters

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.

{
    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.

const records = await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>');

Parameters

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.

await nango.startSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>')

Parameters

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.

await nango.startSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>')

Parameters

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.

await nango.syncStatus('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>')

Parameters

Response

{
    "syncs": [
        {
            "id": "<string>",
            "name": "<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.

await nango.updateSyncConnectionFrequency('<INTEGRATION-ID>', 'SYNC_NAME', '<CONNECTION_ID>', '<FREQUENCY>')

Parameters

Response

Get environment variables

Retrieve the environment variables as added in the Nango dashboard.

await nango.getEnvironmentVariables();

Parameters

No parameters.

Response

Actions

Trigger an action

Triggers an action for a connection.

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

Parameters

Response

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

Response

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

Returns

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

Reference

Use Integrations - Reference

Build Integrations - Reference

Node

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)

Get connection metadata

Set connection metadata

Edit connection metadata

Delete a connection

Integration scripts

Get integration scripts config

Syncs

Get records

Trigger sync(s)

Start schedule for sync(s)

Pause schedule for sync(s)

Sync status

Override sync connection frequency

Get environment variables

Actions

Trigger an action

Proxy

Connect

Create a connect session

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)

​Get connection metadata

​Set connection metadata

​Edit connection metadata

​Delete a connection

​Integration scripts

​Get integration scripts config

​Syncs

​Get records

​Trigger sync(s)

​Start schedule for sync(s)

​Pause schedule for sync(s)

​Sync status

​Override sync connection frequency

​Get environment variables

​Actions

​Trigger an action

​Proxy

​Connect

​Create a connect session

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)

Get connection metadata

Set connection metadata

Edit connection metadata

Delete a connection

Integration scripts

Get integration scripts config

Syncs

Get records

Trigger sync(s)

Start schedule for sync(s)

Pause schedule for sync(s)

Sync status

Override sync connection frequency

Get environment variables

Actions

Trigger an action

Proxy

Connect

Create a connect session