Node
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
...
}
...
}
Integrations
List all integrations
Returns a list of integrations.
await nango.listIntegrations()
Example Response
Get an integration
Returns a specific integration.
await nango.getIntegration(<INTEGRATION-ID>);
Parameters
Example Response
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
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
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 (overrides existing metadata).
await nango.setMetadata('<INTEGRATION-ID>', 'CONNECTION-ID', { 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });
Parameters
Response
Empty response.
Edit connection metadata
Edit custom metadata for the connection. Only overrides specified properties, not the entire metadata.
await nango.updateMetadata('<INTEGRATION-ID>', 'CONNECTION-ID', { 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });
Parameters
Response
Empty 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
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.
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.
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
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
Questions, problems, feedback? Please reach out in the Slack community.
Was this page helpful?