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.:
Instantiate the Nango class:
import { Nango } from '@nangohq/node' ; const nango = new Nango ({ secretKey: '<SECRET-KEY>' }); Parameters Get your secret key in the environment settings of the Nango UI. THis key should never be shared.
Omitting the host points to Nango Cloud. For local development, use http://localhost:3003. Use your instance URL if self-hosting.
Integrations List all integrations Returns a list of integrations.
await nango . listIntegrations () Example Response { "configs" : [ { "unique_key" : "slack-nango-community" , "provider" : "slack" }, { "unique_key" : "github-prod" , "provider" : "github" }, ] } Get an integration Returns a specific integration.
await nango . getIntegration ( < INTEGRATION-ID > ); Parameters includeIntegrationCredentials
Defaults to false.
Example Response { "config" : { "unique_key" : "slack-nango-community" , "provider" : "slack" , "syncs" : [ { "name" : "slack-messages" , "created_at" : "2023-10-16T08:45:26.241Z" , "updated_at" : "2023-10-16T08:45:26.241Z" , "description" : "Continuously fetch the latest Slack messages. Details: full refresh. Required scopes(s): channels:read, groups:read, mpim:read, im:read" } ], "actions" : [ { "name" : "github-list-repos-action" , "created_at" : "2023-10-17T17:28:03.839Z" , "updated_at" : "2023-10-17T17:28:03.839Z" } ] } } 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 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 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 Example Response { "config" : { "unique_key" : "slack-nango-community" , "provider" : "slack" } } Connections List connections Returns a list of connections without credentials.
await nango . listConnections (); Parameters Filter the list of connections based on this connection ID. If ommitted, returns all connections.
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 }, { "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" } } ] } Get a connection (with credentials) Returns a specific connection with credentials.
await nango . getConnection (); The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth). If you do not want to deal with collecting & injecting credentials in requests for multiple authentication types, use the Proxy (step-by-step guide ). Every time 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 you always fetch the token just before you use it to make sure it is fresh!
Parameters 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" }, "account_id" : 0 , "metadata" : { "myProperty" : "yes" , "filter" : "closed=true" } } 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 The integration ID of the connection.
Example Response { "custom_key1" : "custom_value1" } Set custom metadata for the connection (overrides existing metadata).
await nango . setMetadata ( '<INTEGRATION-ID>' , 'CONNECTION-ID' , { 'CUSTOM_KEY1' : 'CUSTOM_VALUE1' }); Parameters The integration ID of the connection.
metadata
Record<string, any>
required
The custom metadata to store in the connection.
Response Empty response.
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 The integration ID of the connection.
metadata
Record<string, any>
required
The custom metadata to store in the connection.
Response Empty response.
Delete a connection Deletes a specific connection.
await nango . deleteConnection ( '<INTEGRATION-ID>' , 'CONNECTION-ID' ); Parameters The integration ID of the connection.
Response Empty 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 The name of the model of the data you want to retrieve.
Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed only records added or updated after this timestamp are returned, otherwise all records are returned. In particular, when receiving a webhook from Nango notifying you that new data is available, pass the timestamp you get from the webhook in this delta parameter. You will only returned the data that was edited since the previous notification.
The maximum number of records to return. Defaults to 100.
Base-64-encoded value that can be used to fetch the next page of results. The cursor will be included until there are no more results to paginate through.
Filter to only show results that have been added or updated or deleted. Helpful when used in conjuction with the delta parameter to retrieve a subset or records that were added, updated, or deleted with the latest sync. Available options: added, updated, deleted
Example Response { records : [ { id : 123 , ..., // Fields as specified in the model you queried _nango_metadata : { deleted_at : null , last_action : 'ADDED' , first_seen_at : ' 2023-09-18 T 15 : 20 : 35.941305 + 00 : 00 ' , last_modified_at : ' 2023-09-18 T 15 : 20 : 35.941305 + 00 : 00 ' } }, ... ], 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.
const records = await nango . triggerSync ( '<INTEGRATION-ID>' , [ 'SYNC_NAME1' , 'SYNC_NAME2' ], '<CONNECTION_ID>' ); Parameters The name of the syncs to trigger. If the array is empty, all syncs are triggered.
The connection ID. If omitted, the sync will trigger for all relevant connections.
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 The name of the syncs that should be triggered.
The connection ID. If ommitted, 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.
await nango . startSync ( '<INTEGRATION-ID>' , [ 'SYNC_NAME1' , 'SYNC_NAME2' ], '<CONNECTION_ID>' ) Parameters The name of the syncs that should be paused.
The connection ID. If ommitted, 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.
await nango . syncStatus ( '<INTEGRATION-ID>' , [ 'SYNC_NAME1' , 'SYNC_NAME2' ], '<CONNECTION_ID>' ) Parameters The name of the syncs you want to fetch a status for. Pass in ”*” to return all syncs.
The connection ID. If omitted, all connections will be surfaced.
Response { "syncs" : [ { "id" : "<string>" , "name" : "<string>" , "status" : "RUNNING" , "type" : "INCREMENTAL" , "finishedAt" : "<string>" , "nextScheduledSyncAt" : "<string>" , "frequency" : "<string>" , "latestResult" : {} } ] } 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 The frequency you want to set (ex: ‘every hour’). Set to null to revert to the default frequency.
Response { "frequency" : "<string>" } 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 The name of the action to trigger.
The necessary input for your action’s runAction function.
Response { "your-properties" : "The data returned by the action" } Proxy Proxy - GET requests Triggers an action for a connection.
const res = await nango . get ({ endpoint: '/endpoint' , providerConfigKey: '<INTEGRATION-ID>' , connectionId: '<CONNECTION-ID>' , baseUrlOverride: 'https://base-url.com' }); Parameters The endpoint of the request.
The integration ID (for credential injection).
The connection ID (for credential injection).
The headers of the request.
params
Record<string, string | number>
The query parameters 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 ommitted if the base URL is configured for this API in the providers.yaml . Override the decompress option when making requests. Optional, defaults to false
responseType
'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
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
Proxy - POST requests Triggers an action for a connection.
const res = await nango . post ({ endpoint: '/endpoint' , providerConfigKey: '<INTEGRATION-ID>' , connectionId: '<CONNECTION-ID>' , baseUrlOverride: 'https://base-url.com' }); Parameters The endpoint of the request.
The integration ID (for credential injection).
The connection ID (for credential injection).
The headers of the request.
params
Record<string, string | number>
The query parameters 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 ommitted if the base URL is configured for this API in the providers.yaml . Override the decompress option when making requests. Optional, defaults to false
responseType
'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
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
Proxy - PUT requests Triggers an action for a connection.
const res = await nango . put ({ endpoint: '/endpoint' , providerConfigKey: '<INTEGRATION-ID>' , connectionId: '<CONNECTION-ID>' , baseUrlOverride: 'https://base-url.com' }); Parameters The endpoint of the request.
The integration ID (for credential injection).
The connection ID (for credential injection).
The headers of the request.
params
Record<string, string | number>
The query parameters 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 ommitted if the base URL is configured for this API in the providers.yaml . Override the decompress option when making requests. Optional, defaults to false
responseType
'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
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
Proxy - PATCH requests Triggers an action for a connection.
const res = await nango . patch ({ endpoint: '/endpoint' , providerConfigKey: '<INTEGRATION-ID>' , connectionId: '<CONNECTION-ID>' , baseUrlOverride: 'https://base-url.com' }); Parameters The endpoint of the request.
The integration ID (for credential injection).
The connection ID (for credential injection).
The headers of the request.
params
Record<string, string | number>
The query parameters 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 ommitted if the base URL is configured for this API in the providers.yaml . Override the decompress option when making requests. Optional, defaults to false
responseType
'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
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
Proxy - DELETE requests Triggers an action for a connection.
const res = await nango . delete ({ endpoint: '/endpoint' , providerConfigKey: '<INTEGRATION-ID>' , connectionId: '<CONNECTION-ID>' , baseUrlOverride: 'https://base-url.com' }); Parameters The endpoint of the request.
The integration ID (for credential injection).
The connection ID (for credential injection).
The headers of the request.
params
Record<string, string | number>
The query parameters 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 ommitted if the base URL is configured for this API in the providers.yaml . Override the decompress option when making requests. Optional, defaults to false
responseType
'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
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
