Create an integration

curl --request POST \
  --url https://api.nango.dev/integrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "unique_key": "<string>",
  "provider": "<string>",
  "display_name": "<string>",
  "forward_webhooks": true,
  "credentials": {
    "client_id": "<string>",
    "client_secret": "<string>",
    "scopes": "<string>",
    "webhook_secret": "<string>"
  },
  "integration_config": {},
  "custom": {}
}
'

import requests

url = "https://api.nango.dev/integrations"

payload = {
    "unique_key": "<string>",
    "provider": "<string>",
    "display_name": "<string>",
    "forward_webhooks": True,
    "credentials": {
        "client_id": "<string>",
        "client_secret": "<string>",
        "scopes": "<string>",
        "webhook_secret": "<string>"
    },
    "integration_config": {},
    "custom": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    unique_key: '<string>',
    provider: '<string>',
    display_name: '<string>',
    forward_webhooks: true,
    credentials: {
      client_id: '<string>',
      client_secret: '<string>',
      scopes: '<string>',
      webhook_secret: '<string>'
    },
    integration_config: {},
    custom: {}
  })
};

fetch('https://api.nango.dev/integrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nango.dev/integrations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'unique_key' => '<string>',
    'provider' => '<string>',
    'display_name' => '<string>',
    'forward_webhooks' => true,
    'credentials' => [
        'client_id' => '<string>',
        'client_secret' => '<string>',
        'scopes' => '<string>',
        'webhook_secret' => '<string>'
    ],
    'integration_config' => [
        
    ],
    'custom' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nango.dev/integrations"

	payload := strings.NewReader("{\n  \"unique_key\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"forward_webhooks\": true,\n  \"credentials\": {\n    \"client_id\": \"<string>\",\n    \"client_secret\": \"<string>\",\n    \"scopes\": \"<string>\",\n    \"webhook_secret\": \"<string>\"\n  },\n  \"integration_config\": {},\n  \"custom\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nango.dev/integrations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"unique_key\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"forward_webhooks\": true,\n  \"credentials\": {\n    \"client_id\": \"<string>\",\n    \"client_secret\": \"<string>\",\n    \"scopes\": \"<string>\",\n    \"webhook_secret\": \"<string>\"\n  },\n  \"integration_config\": {},\n  \"custom\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nango.dev/integrations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"unique_key\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"forward_webhooks\": true,\n  \"credentials\": {\n    \"client_id\": \"<string>\",\n    \"client_secret\": \"<string>\",\n    \"scopes\": \"<string>\",\n    \"webhook_secret\": \"<string>\"\n  },\n  \"integration_config\": {},\n  \"custom\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "unique_key": "slack-nango-community",
    "display_name": "Slack",
    "provider": "slack",
    "logo": "http://localhost:3003/images/template-logos/github.svg",
    "missing_fields": [],
    "created_at": "2023-10-16T08:45:26.241Z",
    "updated_at": "2023-10-16T08:45:26.241Z",
  }
}

POST

integrations

Create an integration

curl --request POST \
  --url https://api.nango.dev/integrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "unique_key": "<string>",
  "provider": "<string>",
  "display_name": "<string>",
  "forward_webhooks": true,
  "credentials": {
    "client_id": "<string>",
    "client_secret": "<string>",
    "scopes": "<string>",
    "webhook_secret": "<string>"
  },
  "integration_config": {},
  "custom": {}
}
'

import requests

url = "https://api.nango.dev/integrations"

payload = {
    "unique_key": "<string>",
    "provider": "<string>",
    "display_name": "<string>",
    "forward_webhooks": True,
    "credentials": {
        "client_id": "<string>",
        "client_secret": "<string>",
        "scopes": "<string>",
        "webhook_secret": "<string>"
    },
    "integration_config": {},
    "custom": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    unique_key: '<string>',
    provider: '<string>',
    display_name: '<string>',
    forward_webhooks: true,
    credentials: {
      client_id: '<string>',
      client_secret: '<string>',
      scopes: '<string>',
      webhook_secret: '<string>'
    },
    integration_config: {},
    custom: {}
  })
};

fetch('https://api.nango.dev/integrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nango.dev/integrations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'unique_key' => '<string>',
    'provider' => '<string>',
    'display_name' => '<string>',
    'forward_webhooks' => true,
    'credentials' => [
        'client_id' => '<string>',
        'client_secret' => '<string>',
        'scopes' => '<string>',
        'webhook_secret' => '<string>'
    ],
    'integration_config' => [
        
    ],
    'custom' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nango.dev/integrations"

	payload := strings.NewReader("{\n  \"unique_key\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"forward_webhooks\": true,\n  \"credentials\": {\n    \"client_id\": \"<string>\",\n    \"client_secret\": \"<string>\",\n    \"scopes\": \"<string>\",\n    \"webhook_secret\": \"<string>\"\n  },\n  \"integration_config\": {},\n  \"custom\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nango.dev/integrations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"unique_key\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"forward_webhooks\": true,\n  \"credentials\": {\n    \"client_id\": \"<string>\",\n    \"client_secret\": \"<string>\",\n    \"scopes\": \"<string>\",\n    \"webhook_secret\": \"<string>\"\n  },\n  \"integration_config\": {},\n  \"custom\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nango.dev/integrations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"unique_key\": \"<string>\",\n  \"provider\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"forward_webhooks\": true,\n  \"credentials\": {\n    \"client_id\": \"<string>\",\n    \"client_secret\": \"<string>\",\n    \"scopes\": \"<string>\",\n    \"webhook_secret\": \"<string>\"\n  },\n  \"integration_config\": {},\n  \"custom\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "unique_key": "slack-nango-community",
    "display_name": "Slack",
    "provider": "slack",
    "logo": "http://localhost:3003/images/template-logos/github.svg",
    "missing_fields": [],
    "created_at": "2023-10-16T08:45:26.241Z",
    "updated_at": "2023-10-16T08:45:26.241Z",
  }
}

Requires an API key with the environment:integrations:create scope. Learn more about API key scopes.

Use a Nango-managed developer app

To skip registering your own app with the provider, set credentials to { "type": "NANGO_MANAGED" }. The integration then uses Nango’s managed developer app for the provider.

{
  "provider": "github",
  "unique_key": "github",
  "credentials": { "type": "NANGO_MANAGED" }
}

This works for OAUTH1, OAUTH2, and APP providers that Nango has a managed app for. Other providers return a 400. You can’t combine it with integration_config or custom, and you can’t edit the credentials afterwards.

{
  "data": {
    "unique_key": "slack-nango-community",
    "display_name": "Slack",
    "provider": "slack",
    "logo": "http://localhost:3003/images/template-logos/github.svg",
    "missing_fields": [],
    "created_at": "2023-10-16T08:45:26.241Z",
    "updated_at": "2023-10-16T08:45:26.241Z",
  }
}

Authorizations

Authorization

string

header

required

An Environment API key from your Nango environment, or an Account API key for account-level endpoints.

Body

application/json

unique_key

string

required

A unique integration ID, which you will use in the other API calls to reference this integration.

provider

string

required

The provider unique name.

display_name

string

The integration display name.

forward_webhooks

boolean

Whether to forward webhooks received for this integration. Defaults to true.

credentials

object

Developer app credentials for the integration. Omit them to create the integration without credentials and provide them later, either with an update request or per connection at connection time. Set type to NANGO_MANAGED to use a Nango-managed developer app instead.

Show child attributes

integration_config

object

Provider-specific configuration for providers that declare an integration_config schema (e.g. private-api-generic, aws-sigv4). Keys and required fields depend on the provider; values are validated against the provider schema.

Show child attributes

custom

object

Free-form key-value settings stored on the integration, for providers without an integration_config schema. Rejected for providers that declare one; use integration_config instead.

Show child attributes

Response

Successfully created an integration

data

object

required

Show child attributes

Getting started

Guides

Reference

Create an integration

Use a Nango-managed developer app

Authorizations

Body

Response