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
...
}
...
}
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
The ID of the API provider in Nango (cf. providers.yaml for a list of API provider IDs.)
The integration ID.
The credentials to include depend on the specific integration that you want to create.
Example Response
{
"config": {
"unique_key": "slack-nango-community",
"provider": "slack"
}
}
Update an integration
Edits an integration (only for OAuth APIs).
await nango.updateIntegration(<PROVIDER-ID>, <INTEGRATION-ID>);
Parameters
The ID of the API provider in Nango (cf. providers.yaml for a list of API provider IDs.)
The integration ID.
The credentials to include depend on the specific integration that you want to create.
Example Response
{
"config": {
"unique_key": "slack-nango-community",
"provider": "slack"
}
}
Delete an integration
Deletes a specific integration.
await nango.deleteIntegration(<INTEGRATION-ID>);
Parameters
The integration ID.
Example Response
{
"config": {
"unique_key": "slack-nango-community",
"provider": "slack"
}
}
Connections
List connections
Returns a list of connections without credentials.
await nango.listConnections();
Parameters
Optional. Will exactly match a given connectionId. Can return multiple connections with the same ID across integrations.
Optional. Search connections. Will search in connection ID or end user profile.
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"}],
"end_user": {
"id": "your-internal-id",
"email": "user@example.com",
"organization": {
"id": "user-organization-id"
}
}
}
]
}
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
The integration ID.
The connection ID.
Defaults to false
. If false
, the token will only be refreshed if it expires within 15 minutes. If true
, a token refresh attempt will happen on each request. This is only useful for testing and should not be done at high traffic.
Defaults to false
. If false
, the refresh token is not included in the response, otherwise it is. In production, it is not advised to return the refresh token, for security reasons, since only the access token is needed to sign requests.
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"
},
"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
{
"custom_key1": "custom_value1"
}
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
{
"connection_id": "<string | [string]>",
"provider_config_key": "<string>",
"metadata": {
"CUSTOM_KEY1": "CUSTOM_VALUE1"
}
}
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
{
"connection_id": "<string | [string]>",
"provider_config_key": "<string>",
"metadata": {
"CUSTOM_KEY1": "CUSTOM_VALUE1"
}
}
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"
}
]
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');
{
"data": [
{
"name": "calendars",
"description": "Sync the user's calendar list.\nIncludes all calendars the user has access to.",
"parameters": {
"type": "object",
"properties": {},
"required": []
}
},
{
"name": "events",
"description": "Sync calendar events from the primary calendar.\nIncludes events from the past month.",
"parameters": {
"type": "object",
"properties": {},
"required": []
}
},
{
"name": "cancel-event",
"description": "Cancel/delete an event by searching for it.\n\nInput parameters:\n- title: The title of the event to cancel\n- date: The date of the event in ISO format\n- time: The time of the event in 24-hour format (HH:mm)\n- calendar: Calendar ID where to search for the event\n- id: Calendar identifier\n- summary: Calendar name/title\n- description: Calendar description\n- location: Calendar location\n- timeZone: Time zone of the calendar\n- backgroundColor: Calendar color in UI\n- foregroundColor: Text color in UI\n- selected: Whether the calendar is selected in UI\n- accessRole: User's access role for the calendar\n- primary: Whether this is the primary calendar",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Calendar identifier"
},
"summary": {
"type": "string",
"description": "Calendar name/title"
},
"description": {
"type": "string",
"description": "Calendar description"
},
"location": {
"type": "string",
"description": "Calendar location"
},
"timeZone": {
"type": "string",
"description": "Time zone of the calendar"
},
"backgroundColor": {
"type": "string",
"description": "Calendar color in UI"
},
"foregroundColor": {
"type": "string",
"description": "Text color in UI"
},
"selected": {
"type": "boolean",
"description": "Whether the calendar is selected in UI"
},
"accessRole": {
"type": "string",
"description": "User's access role for the calendar"
},
"primary": {
"type": "boolean",
"description": "Whether this is the primary calendar"
},
"title": {
"type": "string",
"description": "The title of the event to cancel"
},
"date": {
"type": "string",
"description": "The date of the event in ISO format"
},
"time": {
"type": "string",
"description": "The time of the event in 24-hour format (HH:mm)"
},
"calendar": {
"type": "string",
"description": "Calendar ID where to search for the event"
}
},
"required": [
"id",
"summary"
]
}
},
{
"name": "create-event",
"description": "Create a new calendar event.\n\nInput parameters:\n- summary: The title/summary of the event\n- description: A detailed description of the event\n- location: The location of the event\n- start: The start time of the event in ISO format\n- end: The end time of the event in ISO format\n- attendees: List of email addresses to invite\n- recurrence: List of recurrence rules in RRULE format\n- calendar: Calendar ID to create the event in\n- id: Calendar identifier\n- timeZone: Time zone of the calendar\n- backgroundColor: Calendar color in UI\n- foregroundColor: Text color in UI\n- selected: Whether the calendar is selected in UI\n- accessRole: User's access role for the calendar\n- primary: Whether this is the primary calendar",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Calendar identifier"
},
"summary": {
"type": "string",
"description": "The title/summary of the event"
},
"description": {
"type": "string",
"description": "A detailed description of the event"
},
"location": {
"type": "string",
"description": "The location of the event"
},
"timeZone": {
"type": "string",
"description": "Time zone of the calendar"
},
"backgroundColor": {
"type": "string",
"description": "Calendar color in UI"
},
"foregroundColor": {
"type": "string",
"description": "Text color in UI"
},
"selected": {
"type": "boolean",
"description": "Whether the calendar is selected in UI"
},
"accessRole": {
"type": "string",
"description": "User's access role for the calendar"
},
"primary": {
"type": "boolean",
"description": "Whether this is the primary calendar"
},
"start": {
"type": "string",
"description": "The start time of the event in ISO format"
},
"end": {
"type": "string",
"description": "The end time of the event in ISO format"
},
"attendees": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of email addresses to invite"
},
"recurrence": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of recurrence rules in RRULE format"
},
"calendar": {
"type": "string",
"description": "Calendar ID to create the event in"
}
},
"required": [
"id",
"summary",
"start",
"end"
]
}
},
{
"name": "move-event",
"description": "Move an event to a different time or calendar.\n\nInput parameters:\n- eventId: The ID of the event to move\n- title: The title of the event to move\n- sourceStart: The current start time of the event\n- start: The new start time for the event in ISO format\n- end: The new end time for the event in ISO format\n- calendar: Calendar ID to move the event to\n- id: Calendar identifier\n- summary: Calendar name/title\n- description: Calendar description\n- location: Calendar location\n- timeZone: Time zone of the calendar\n- backgroundColor: Calendar color in UI\n- foregroundColor: Text color in UI\n- selected: Whether the calendar is selected in UI\n- accessRole: User's access role for the calendar\n- primary: Whether this is the primary calendar",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Calendar identifier"
},
"summary": {
"type": "string",
"description": "Calendar name/title"
},
"description": {
"type": "string",
"description": "Calendar description"
},
"location": {
"type": "string",
"description": "Calendar location"
},
"timeZone": {
"type": "string",
"description": "Time zone of the calendar"
},
"backgroundColor": {
"type": "string",
"description": "Calendar color in UI"
},
"foregroundColor": {
"type": "string",
"description": "Text color in UI"
},
"selected": {
"type": "boolean",
"description": "Whether the calendar is selected in UI"
},
"accessRole": {
"type": "string",
"description": "User's access role for the calendar"
},
"primary": {
"type": "boolean",
"description": "Whether this is the primary calendar"
},
"eventId": {
"type": "string",
"description": "The ID of the event to move"
},
"title": {
"type": "string",
"description": "The title of the event to move"
},
"sourceStart": {
"type": "string",
"description": "The current start time of the event"
},
"start": {
"type": "string",
"description": "The new start time for the event in ISO format"
},
"end": {
"type": "string",
"description": "The new end time for the event in ISO format"
},
"calendar": {
"type": "string",
"description": "Calendar ID to move the event to"
}
},
"required": [
"id",
"summary",
"start",
"end"
]
}
},
{
"name": "whoami",
"description": "Get information about the authenticated user.\n\nNo input parameters.",
"parameters": {
"type": "object",
"properties": {},
"required": []
}
},
{
"name": "invite-user-to-repository",
"description": "Invite a user to a GitHub repository.\n\nInput parameters:\n- owner: The owner (user or organization) of the repository\n- repo: The name of the repository to invite the user to\n- username: The GitHub username of the user to invite\n- permission: The permission level to grant (\"pull\", \"push\", \"admin\", \"maintain\", \"triage\")",
"parameters": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "The owner (user or organization) of the repository"
},
"repo": {
"type": "string",
"description": "The name of the repository to invite the user to"
},
"username": {
"type": "string",
"description": "The GitHub username of the user to invite"
},
"permission": {
"type": "string",
"description": "The permission level to grant (\"pull\", \"push\", \"admin\", \"maintain\", \"triage\")"
}
},
"required": [
"owner",
"repo",
"username"
]
}
}
]
}
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
The integration ID.
The connection ID.
The name of the model of the data you want to retrieve.
The variant of the model to fetch. When omitted, the default base variant is used.
Each record from this endpoint comes with a synchronization cursor in _nango_metadata.cursor
.
Save the last fetched record’s cursor to track how far you’ve synced.
By providing the cursor to this method, you’ll continue syncing from where you left off, receiving only post-cursor changes.
This same cursor is used to paginate through the results of this endpoint.
The maximum number of records to return. Defaults to 100.
Filter to only show results that have been added or updated or deleted.
Available options: added, updated, deleted
Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.
An array of string containing a list of your records IDs. The list will be filtered to include only the records with a matching ID.
DEPRECATED (use modifiedAfter) Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.
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.
// Simple usage with sync names
const result = await nango.triggerSync('<INTEGRATION-ID>', ['SYNC_NAME1', 'SYNC_NAME2'], '<CONNECTION_ID>', 'incremental');
// Using variants
const resultWithVariants = await nango.triggerSync('<INTEGRATION-ID>', [
{ name: 'SYNC_NAME1', variant: 'VARIANT_A' },
'SYNC_NAME2' // Uses default base variant
], '<CONNECTION_ID>', 'incremental');
Parameters
The integration ID.
The name of the syncs to trigger. If the array is empty, all syncs are triggered. Each sync can be specified as either:
- A string: the sync name (uses the default base variant)
- An object: with name and variant properties to target a specific sync variant
The connection ID. If omitted, the sync will trigger for all relevant connections.
The mode in which to trigger the syncs.
incremental
: Triggers a new sync job while preserving the “lastSyncDate”.full_refresh
: Resets the “lastSyncDate” associated with the sync before triggering a new sync job.full_refresh_and_clear_cache
: Resets the “lastSyncDate” and deletes all records associated with the sync before triggering a new sync job.
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
The integration ID.
The name of the syncs that should be triggered. Each sync can be specified as either:
- A string: the sync name (uses the default base variant)
- An object: with name and variant properties to target a specific sync variant
The connection ID. If omitted, the sync will trigger for all relevant connections.
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
The integration ID.
The name of the syncs that should be paused. Each sync can be specified as either:
- A string: the sync name (uses the default base variant)
- An object: with name and variant properties to target a specific sync variant
The connection ID. If omitted, the sync will pause for all relevant connections.
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
The integration ID.
Either ”*” to return all syncs, or an array of syncs to fetch status for. When using an array, each sync can be specified as either:
- A string: the sync name (uses the default base variant)
- An object: with name and variant properties to target a specific sync variant
The connection ID. If omitted, all connections will be surfaced.
Response
{
"syncs": [
{
"id": "<string>",
"connection_id": "<string>",
"name": "<string>",
"variant": "<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.
// 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
The integration ID.
The sync to update. Can be specified as either:
- A string: the sync name (uses the default base variant)
- An object: with name and variant properties to target a specific sync variant
The connection ID.
The frequency you want to set (ex: ‘every hour’). Set to null
to revert to the default frequency. Uses the https://github.com/vercel/ms notations. Min frequency: 5 minutes.
Response
{
"frequency": "<string>"
}
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
{
"id": "12345",
"name": "SYNC_NAME",
"variant": "VARIANT_NAME"
}
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
{
"success": true
}
Get environment variables
Retrieve the environment variables as added in the Nango dashboard.
await nango.getEnvironmentVariables();
Parameters
No parameters.
Response
[
{
"name": "MY_SECRET_KEY",
"value": "SK_373892NSHFNCOWFO..."
}
]
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
{
"your-properties": "The data returned by the action"
}
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
The endpoint of the request.
The integration ID (for credential injection).
The connection ID (for credential injection).
The headers of the request.
The query parameters of the request.
The body of the request.
The number of retries in case of failure (with exponential back-off). Optional, default 0.
Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED
The API base URL. Can be omitted if the base URL is configured for this API in the providers.yaml.
Override the decompress option when making requests. Optional, defaults to false
The type of the response.
Response
The response from the external API is passed back to you exactly as Nango gets it:
- response code
- response headers
- response body
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
An array of integration IDs that are allowed for this session.
Default configuration for specific integrations.
Returns
{
"data": {
"token": "nango_connect_session_4603dbca8a588315ba69b5bfddde52e72d312dc2d2870bd5e45da6357333601c",
"expires_at": "2024-09-27T19:49:51.449Z"
}
}
Create a reconnect session
Create a reconnect session for a given connection_id
. Optionally, you can set end_user
and organization
to update those attributes of the connection.
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
end_user: {
id: '<END-USER-ID>',
email: '<END-USER-EMAIL>',
display_name: '<END-USER-NAME>'
},
organization: {
id: '<ORGANIZATION-ID>',
display_name: '<ORGANIZATION-NAME>'
},
integrations_config_defaults: {
<INTEGRATION-ID-1>: {
connection_config: {
<CONFIG-KEY>: '<VALUE>'
}
}
}
});
Parameters
The unique identifier for the connection.
The unique identifier for the integration.
Default configuration for specific integrations.
Returns
{
"data": {
"token": "nango_connect_session_4603dbca8a588315ba69b5bfddde52e72d312dc2d2870bd5e45da6357333601c",
"expires_at": "2024-09-27T19:49:51.449Z"
}
}
Webhook
Verify Webhook Signature
Asserts that a Webhook is coming from Nango’s backend.
async (req, res) => {
const signature = req.headers['x-nango-signature'];
const isValid = nango.verifyWebhookSignature(signature, req.body);
}
Questions, problems, feedback? Please reach out in the Slack community.
- 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
- Create sync variant
- Delete sync variant
- Get environment variables
- Actions
- Trigger an action
- Proxy
- Connect
- Create a connect session
- Create a reconnect session
- Webhook
- Verify Webhook Signature