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.