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/nodeInstantiate the Nango class:
import { Nango } from '@nangohq/node';
const nango = new Nango({ apiKey: '<API-KEY>' });Parameters
Rate limits
The Tenklo 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({ uniqueKey: <UNIQUE_KEY> });
// Deprecated
await nango.getIntegration(<INTEGRATION-ID>);Parameters
Example Response
missing_fields lists the credential fields the integration may need before connections can be created, for example oauth_client_id. It is empty once the integration is fully configured, when it uses a Nango-provided developer app, or when the auth mode collects everything at connection time.
Create an integration
Create a new integration.
await nango.createIntegration({ provider: '<PROVIDER-ID>', unique_key: '<UNIQUE_KEY>' });Parameters
Example Response
Update an integration
Patch an integration. The first argument identifies the integration; all body fields are optional and only the fields you pass are updated.
await nango.updateIntegration({ uniqueKey: '<UNIQUE_KEY>' }, { display_name: 'New name' });Parameters
Example Response
Delete an integration
Deletes a specific integration.
await nango.deleteIntegration(<UNIQUE_KEY>);Parameters
Example Response
Connect
Create a connect session
Create a connect session. The token is short-lived and lasts for 30 minutes.
const { data } = await nango.createConnectSession({
// Recommended: copied onto the connection and included in auth webhooks.
tags: {
end_user_id: '<END-USER-ID>',
end_user_email: '<END-USER-EMAIL>',
organization_id: '<ORGANIZATION-ID>'
},
allowed_integrations: ['<INTEGRATION-ID-1>', '<INTEGRATION-ID-2>'],
integrations_config_defaults: {
<INTEGRATION-ID-1>: {
connection_config: {
<CONFIG-KEY>: '<VALUE>'
}
}
}
});Parameters
Returns
Create a reconnect session
Create a reconnect session for a given connection_id.
You can pass tags to update connection attribution during reconnection.
Use this method when a user needs to input new credentials or to manually refresh token.
connection_id created with a session token.const { data } = await nango.createReconnectSession({
// Required
connection_id: '<CONNECTION-ID>',
integration_id: '<INTEGRATION-ID>',
// Optional
tags: {
end_user_id: '<END-USER-ID>',
end_user_email: '<END-USER-EMAIL>',
organization_id: '<ORGANIZATION-ID>'
},
integrations_config_defaults: {
<INTEGRATION-ID-1>: {
connection_config: {
<CONFIG-KEY>: '<VALUE>'
}
}
}
});Parameters
Returns
Connections
List connections
Returns a list of connections without credentials.
await nango.listConnections({
connectionId: 'connection-id',
integrationId: 'integration-456',
limit: 100,
tags: { "end_user_id": 'user-123' }
});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, Tenklo 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
Patch a connection
Patch a connection.
await nango.patchConnection({
connectionId: '<CONNECTION-ID>',
provider_config_key: '<INTEGRATION-ID>'
},
{ ...body });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 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.
Wait for connection
Waits for a connection to be created for a given end user and integration. This is useful in agentic flows where you need to wait for a user to complete the OAuth flow before proceeding.
const connection = await nango.waitForConnection('<INTEGRATION-ID>', '<END-USER-ID>');This method polls for a connection every 2 seconds for up to 60 seconds (30 attempts). If no connection is found within this time, it will throw a timeout error.
Parameters
Example Response
Integration functions
List functions
Returns the functions available to an integration, with pagination.
await nango.listFunctions({ uniqueKey: 'github' });Filter by function type, name, or page:
await nango.listFunctions({ uniqueKey: 'github' }, { type: 'action', search: 'issue', page: 0, limit: 20 });Parameters
Catalog actions have id: null, last_deployed: null, enabled: true, and source: "tools-catalog". A deployed action with the same name takes precedence.
Example Response
Get a function
Retrieves a function available to an integration. This can be a deployed function or a Tenklo catalog action.
await nango.getFunction({ uniqueKey: 'github', name: 'create-issue' });Pass type to disambiguate when a sync and an action share the same name:
await nango.getFunction({ uniqueKey: 'github', name: 'issues' }, { type: 'sync' });Parameters
Example Response
Get function code
Retrieves the source code of a function. For a Tenklo catalog action, the response contains the current catalog source even though the action has not been deployed.
await nango.getFunctionCode({ uniqueKey: 'github', name: 'create-issue' }, { type: 'action' });Parameters
Example Response
Delete a function
Deletes a deployed function of an integration. The type is required.
await nango.deleteFunction({ uniqueKey: 'github', name: 'create-issue' }, { type: 'action' });Parameters
Example Response
Get integration functions config
Return the configuration for all integration functions
const scriptsConfig = await nango.getScriptsConfig();Example Response
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');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
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.
Prune records
Prunes record payloads from Tenklo's cache for a given model and connection up to a specified cursor. The payload is emptied but record metadata is retained. Payload can be restored by re-syncing the data.
const result = await nango.pruneRecords({
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>',
model: '<MODEL-NAME>',
untilCursor: '<CURSOR>'
});
console.log(`Pruned ${result.count} records. More records available: ${result.has_more}`);Parameters
Response
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 - trigger sync preserving checkpoint
await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>');
// Reset checkpoint and start fresh
await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1'], '<CONNECTION_ID>', { reset: true });
// Reset checkpoint and clear all cached records
await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1'], '<CONNECTION_ID>', { reset: true, emptyCache: true });
// Using variants
await nango.triggerSync('<INTEGRATION-ID>', [
{ name: 'SYNC_NAME1', variant: 'VARIANT_A' },
'SYNC_NAME2' // Uses default base variant
], '<CONNECTION_ID>', { reset: true });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.
// 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
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
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
Response
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
Response
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
Example Response
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
Example Response
Get environment variables
Retrieve the environment variables as added in the Tenklo 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
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
Response
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
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 requestParameters
Response
Providers
List all providers
Returns a list of providers.
await nango.listProviders()Example Response
Get a provider
Returns a specific provider.
await nango.getProvider({ provider: <NAME> })Example Response
Get provider templates
Returns the function templates available for a provider.
await nango.getProviderTemplates({ provider: <NAME> })Parameters
Example Response
Webhooks from Tenklo
Verify Webhook Signature
Asserts that a Webhook is coming from Tenklo's backend. Verification uses webhookSigningKey when the client is constructed with one, otherwise it falls back to secretKey. On environments created after 2026-04-20 (or any environment that later rotated its API key), the signing key differs from the API key, so construct the client with webhookSigningKey (from Environment Settings > Webhooks > Signing key).
const nango = new Nango({
apiKey: '<API-KEY>',
webhookSigningKey: '<WEBHOOK-SIGNING-KEY>'
});
async (req, res) => {
const isValid = nango.verifyIncomingWebhookRequest(req.body, req.headers);
}Questions, problems, feedback? Please reach out in the Slack community.