Integrations API

An integration is a configured connection to an external provider. It combines a provider (e.g. github, slack) with your OAuth app credentials or API key configuration, and gives you a unique key you use to create connections for your users. Before a user can authenticate with an external service, you must create an integration for that provider in your Nango environment.

All API requests require a secret key passed as a Bearer token. You can find your secret key in the Settings section of the Nango dashboard.

List integrations

curl --request GET \
  --url https://api.nango.dev/integrations \
  --header 'Authorization: Bearer <SECRET_KEY>'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const { configs } = await nango.listIntegrations();

GET /integrations Returns all integrations configured in your environment.

Response

ApiPublicIntegration[]

Hide properties

string

required

Your unique identifier for this integration (e.g. slack-production). Used as provider_config_key when creating connections.

string

required

The provider slug this integration is built on (e.g. slack, github, salesforce).

string

A human-readable name shown in the Connect UI.

string

URL for the provider logo image.

boolean

Whether incoming provider webhooks are forwarded to your configured webhook URL.

string

ISO 8601 timestamp of when the integration was created.

string

ISO 8601 timestamp of when the integration was last updated.

Example response

{
  "data": [
    {
      "unique_key": "slack-nango-community",
      "provider": "slack",
      "display_name": "Slack",
      "logo": "https://api.nango.dev/images/template-logos/slack.svg",
      "forward_webhooks": false,
      "created_at": "2023-10-16T08:45:26.241Z",
      "updated_at": "2023-10-16T08:45:26.241Z"
    },
    {
      "unique_key": "github-prod",
      "provider": "github",
      "display_name": "GitHub",
      "logo": "https://api.nango.dev/images/template-logos/github.svg",
      "forward_webhooks": true,
      "created_at": "2023-10-16T08:45:26.241Z",
      "updated_at": "2023-10-16T08:45:26.241Z"
    }
  ]
}

Get an integration

curl --request GET \
  --url 'https://api.nango.dev/integrations/slack-nango-community?include[]=webhook&include[]=credentials' \
  --header 'Authorization: Bearer <SECRET_KEY>'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const { data } = await nango.getIntegration(
  { uniqueKey: 'slack-nango-community' },
  { include: ['webhook', 'credentials'] }
);

GET /integrations/:uniqueKey Returns a single integration by its unique key.

Path parameters

string

required

The unique key of the integration to retrieve.

Query parameters

string[]

Additional fields to include in the response. Accepts webhook and/or credentials.

Response

object

Hide properties

string

required

The integration’s unique key.

string

required

The provider slug (e.g. slack).

string

Human-readable display name.

string

URL for the provider logo.

boolean

Whether webhooks are forwarded.

string

Present when include[]=webhook. The webhook URL configured for this integration.

object

Present when include[]=credentials. The OAuth app or API credentials for this integration.

Show OAuth2 / OAuth1 / TBA credentials

string

One of OAUTH2, OAUTH1, TBA.

string

OAuth client ID.

string

OAuth client secret (masked).

string

Space or comma-separated OAuth scopes.

string

Secret used to verify incoming webhooks from the provider.

Show GitHub App credentials

string

APP

string

GitHub App ID.

string

PEM private key (masked).

string

Public URL of the GitHub App.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

Example response

{
  "data": {
    "unique_key": "slack-nango-community",
    "provider": "slack",
    "display_name": "Slack",
    "logo": "https://api.nango.dev/images/template-logos/slack.svg",
    "forward_webhooks": false,
    "webhook_url": "https://api.nango.dev/webhook/abc123/slack-nango-community",
    "credentials": {
      "type": "OAUTH2",
      "client_id": "123456789.abcdef",
      "client_secret": "••••••••",
      "scopes": "channels:read,chat:write",
      "webhook_secret": null
    },
    "created_at": "2023-10-16T08:45:26.241Z",
    "updated_at": "2023-10-16T08:45:26.241Z"
  }
}

Create an integration

curl --request POST \
  --url https://api.nango.dev/integrations \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "slack",
    "unique_key": "slack-production",
    "display_name": "Slack",
    "credentials": {
      "type": "OAUTH2",
      "client_id": "123456789.abcdef",
      "client_secret": "your-client-secret",
      "scopes": "channels:read,chat:write"
    }
  }'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const { data } = await nango.createIntegration({
  provider: 'slack',
  unique_key: 'slack-production',
  display_name: 'Slack',
  credentials: {
    type: 'OAUTH2',
    client_id: '123456789.abcdef',
    client_secret: 'your-client-secret',
    scopes: 'channels:read,chat:write'
  }
});

POST /integrations Creates a new integration.

Request body

string

required

The provider slug to use (e.g. slack, github, salesforce). Must match a provider supported by Nango.

string

required

A unique identifier for this integration within your environment (e.g. slack-production). Used as provider_config_key when creating connections.

string

Human-readable name shown in the Connect UI. Defaults to the provider’s default display name.

boolean

When true, incoming webhooks from the provider are forwarded to your environment’s webhook URL.

object

OAuth app credentials or GitHub App credentials. Required for providers that need OAuth.

Show OAuth2 / OAuth1 / TBA

string

required

One of OAUTH2, OAUTH1, TBA.

string

required

OAuth client ID from your developer app.

string

required

OAuth client secret from your developer app.

string

Default OAuth scopes (space or comma-separated). Can be overridden per connection.

string

Secret used to verify incoming provider webhooks.

Show GitHub App

string

required

APP

string

required

Your GitHub App ID.

string

required

Public URL of the GitHub App (e.g. https://github.com/apps/your-app).

string

required

PEM-encoded private key for the GitHub App.

Response

Returns the created integration object. See Get an integration for the response shape.

Example response

{
  "data": {
    "unique_key": "slack-production",
    "provider": "slack",
    "display_name": "Slack",
    "logo": "https://api.nango.dev/images/template-logos/slack.svg",
    "forward_webhooks": false,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Update an integration

curl --request PATCH \
  --url https://api.nango.dev/integrations/slack-production \
  --header 'Authorization: Bearer <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Slack (Production)",
    "credentials": {
      "type": "OAUTH2",
      "client_id": "new-client-id",
      "client_secret": "new-client-secret",
      "scopes": "channels:read,chat:write,users:read"
    }
  }'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

const { data } = await nango.updateIntegration(
  { uniqueKey: 'slack-production' },
  {
    display_name: 'Slack (Production)',
    credentials: {
      type: 'OAUTH2',
      client_id: 'new-client-id',
      client_secret: 'new-client-secret',
      scopes: 'channels:read,chat:write,users:read'
    }
  }
);

PATCH /integrations/:uniqueKey Updates an existing integration. Only the fields you provide are changed.

Path parameters

string

required

The unique key of the integration to update.

Request body

string

Rename the integration’s unique key.

string

New human-readable display name.

boolean

Enable or disable webhook forwarding.

object

Updated OAuth app credentials. Accepts the same shape as Create an integration.

Response

Returns the updated integration object.

Example response

{
  "data": {
    "unique_key": "slack-production",
    "provider": "slack",
    "display_name": "Slack (Production)",
    "logo": "https://api.nango.dev/images/template-logos/slack.svg",
    "forward_webhooks": false,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:00:00.000Z"
  }
}

Delete an integration

curl --request DELETE \
  --url https://api.nango.dev/integrations/slack-production \
  --header 'Authorization: Bearer <SECRET_KEY>'

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<SECRET_KEY>' });

await nango.deleteIntegration('slack-production');

DELETE /integrations/:uniqueKey Permanently deletes an integration and all of its connections.

Deleting an integration also deletes all connections associated with it. This action cannot be undone.

Path parameters

string

required

The unique key of the integration to delete.

Response

Example response

{
  "success": true
}

Overview

Integrations & Connections

Functions & Proxy

SDKs

Integrations API

List integrations

Response

Get an integration

Path parameters

Query parameters

Response

Create an integration

Request body

Response

Update an integration

Path parameters

Request body

Response

Delete an integration

Path parameters

Response

​List integrations

​Response

​Get an integration

​Path parameters

​Query parameters

​Response

​Create an integration

​Request body

​Response

​Update an integration

​Path parameters

​Request body

​Response

​Delete an integration

​Path parameters

​Response

List integrations

Response

Get an integration

Path parameters

Query parameters

Response

Create an integration

Request body

Response

Update an integration

Path parameters

Request body

Response

Delete an integration

Path parameters

Response