Backend SDKs
Node

The Node SDK lets you retrieve API credentials & data, as well as work with Connections from your backend.

Installing & instantiating the node SDK

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

npm i -S @nangohq/node

Instantiate the Nango class:

  • Nango Cloud

  • Localhost

  • Self-hosted

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

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

Auth

Retrieve API credentials

The easiest and fastest way to get the current API credentials.

For OAuth 2 integrations this will return you the current access token (already refreshed if needed). For API key based integrations it will return the API key. For OAuth 1.0a integrations it will return you a small object with the neccessary details to sign the request.

let creds = await nango.getToken('<INTEGRATION-ID>', '<CONNECTION-ID>');

Always fetch the current access_token from Nango before you run an API request.
We refresh the token if needed. Caching it on your side could lead to failed requests.

Retrieve Connection details

Use this method to retrieve all the details Nango stores on a specific Connection:

let connection = await nango.getConnection(
    '<INTEGRATION-ID>',
    '<CONNECTION-ID>',
    '<FORCE_REFRESH?: boolean>', // Optional: attempt to refresh the access access token regardless of its expiration status, defaults to false
    '<REFRESH_TOKEN?: boolean>', // Optional: return the refresh token as part of the response, defaults to false
);

Please check the REST API reference for an example response and the full list of returned fields.

List all connections for a user

let list = await nango.listConnections('<CONNECTION-ID>');

This returns you all Connections of a specific user (i.e. Connection ID):

{
    connections: [
        {
            connection_id: '<CONNECTION-ID>',
            provider: '<INTEGRATION-ID>',
            created: '2023-03-08T09:43:03.725Z'
        },
        // ...
    ];
}

List all connections

let list = await nango.listConnections();

Returns a list of minimalistic Connection objects. This can be helpful if you need to check whether a user has setup a specific Integration. Note that the list does not contain any access credentials and fetching it also does not refresh the access tokens of any Connections.

Please check the REST API reference for an example response and the full list of returned fields.

Sync

Nango Proxy

The Nango Proxy is not available for all APIs yet.
Check the API’s Integrations page (Cmd + K for search) to see if it is available for you API.

If you need additional APIs supported please reach out on the Slack community: We can enable support within a few hours.

To execute proxy requests, use:

const res = await nango.proxy({
    method: 'POST',
    endpoint: '/calendar/v3/users/me/calendarList',
    providerConfigKey: '<INTEGRATION-ID>',
    connectionId: '<CONNECTION-ID>',
    headers: {
        Go: 'Here'
    },
    params: {
        query: 'params!'
    },
    retries: 5, // If response code != 200. Exponential backoff, default is 0
    data: {
        id: 1,
        colorId: 'blue',
        selected: true
    }
});

There are also convenience methods available: nango.get({}), nango.post({}), nango.patch{{}} and nango.delete({}).

Return value
When you call the proxy Nango creates the API request to the external API and runs it for you (possibly with retries).

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

  • Response code
  • Response headers
  • Response body

For the node SDK Nango returns an Axios response object.

Read data

This feature is in private beta. Request access on the community.

Write data

This feature is in private beta. Request access on the community.