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>'

GET /integrations Returns all integrations configured in your environment.

Response

data

ApiPublicIntegration[]

Hide properties

unique_key

string

required

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

provider

string

required

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

display_name

string

A human-readable name shown in the Connect UI.

logo

string

URL for the provider logo image.

forward_webhooks

boolean

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

created_at

string

ISO 8601 timestamp of when the integration was created.

updated_at

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>'

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

Path parameters

uniqueKey

string

required

The unique key of the integration to retrieve.

Query parameters

include

string[]

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

Response

data

object

Hide properties

unique_key

string

required

The integration’s unique key.

provider

string

required

The provider slug (e.g. slack).

display_name

string

Human-readable display name.

logo

string

URL for the provider logo.

forward_webhooks

boolean

Whether webhooks are forwarded.

webhook_url

string

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

credentials

object

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

Show OAuth2 / OAuth1 / TBA credentials

type

string

One of OAUTH2, OAUTH1, TBA.

client_id

string

OAuth client ID.

client_secret

string

OAuth client secret (masked).

scopes

string

Space or comma-separated OAuth scopes.

webhook_secret

string

Secret used to verify incoming webhooks from the provider.

Show GitHub App credentials

type

string

APP

app_id

string

GitHub App ID.

private_key

string

PEM private key (masked).

app_link

string

Public URL of the GitHub App.

created_at

string

ISO 8601 creation timestamp.

updated_at

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"
    }
  }'

POST /integrations Creates a new integration.

Request body

provider

string

required

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

unique_key

string

required

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

display_name

string

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

forward_webhooks

boolean

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

credentials

object

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

Show OAuth2 / OAuth1 / TBA

type

string

required

One of OAUTH2, OAUTH1, TBA.

client_id

string

required

OAuth client ID from your developer app.

client_secret

string

required

OAuth client secret from your developer app.

scopes

string

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

webhook_secret

string

Secret used to verify incoming provider webhooks.

Show GitHub App

type

string

required

APP

app_id

string

required

Your GitHub App ID.

app_link

string

required

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

private_key

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"
    }
  }'

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

Path parameters

uniqueKey

string

required

The unique key of the integration to update.

Request body

unique_key

string

Rename the integration’s unique key.

display_name

string

New human-readable display name.

forward_webhooks

boolean

Enable or disable webhook forwarding.

credentials

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>'

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

uniqueKey

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

Build docs developers (and LLMs) love

Overview

Integrations & Connections

Functions & Proxy

SDKs

​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

Build docs developers (and LLMs) love

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