Import a connection

Upsert a connection

curl --request POST \
  --url https://api.nango.dev/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider_config_key": "<string>",
  "credentials": {
    "oauth_token": "<string>",
    "oauth_token_secret": "<string>",
    "type": "OAUTH1"
  },
  "metadata": {},
  "connection_id": "<string>",
  "connection_config": {},
  "tags": {}
}
'

import requests

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

payload = {
    "provider_config_key": "<string>",
    "credentials": {
        "oauth_token": "<string>",
        "oauth_token_secret": "<string>",
        "type": "OAUTH1"
    },
    "metadata": {},
    "connection_id": "<string>",
    "connection_config": {},
    "tags": {}
}
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({
    provider_config_key: '<string>',
    credentials: {oauth_token: '<string>', oauth_token_secret: '<string>', type: 'OAUTH1'},
    metadata: {},
    connection_id: '<string>',
    connection_config: {},
    tags: {}
  })
};

fetch('https://api.nango.dev/connections', 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/connections",
  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([
    'provider_config_key' => '<string>',
    'credentials' => [
        'oauth_token' => '<string>',
        'oauth_token_secret' => '<string>',
        'type' => 'OAUTH1'
    ],
    'metadata' => [
        
    ],
    'connection_id' => '<string>',
    'connection_config' => [
        
    ],
    'tags' => [
        
    ]
  ]),
  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/connections"

	payload := strings.NewReader("{\n  \"provider_config_key\": \"<string>\",\n  \"credentials\": {\n    \"oauth_token\": \"<string>\",\n    \"oauth_token_secret\": \"<string>\",\n    \"type\": \"OAUTH1\"\n  },\n  \"metadata\": {},\n  \"connection_id\": \"<string>\",\n  \"connection_config\": {},\n  \"tags\": {}\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/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider_config_key\": \"<string>\",\n  \"credentials\": {\n    \"oauth_token\": \"<string>\",\n    \"oauth_token_secret\": \"<string>\",\n    \"type\": \"OAUTH1\"\n  },\n  \"metadata\": {},\n  \"connection_id\": \"<string>\",\n  \"connection_config\": {},\n  \"tags\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"provider_config_key\": \"<string>\",\n  \"credentials\": {\n    \"oauth_token\": \"<string>\",\n    \"oauth_token_secret\": \"<string>\",\n    \"type\": \"OAUTH1\"\n  },\n  \"metadata\": {},\n  \"connection_id\": \"<string>\",\n  \"connection_config\": {},\n  \"tags\": {}\n}"

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

{
  "id": 123,
  "connection_id": "<string>",
  "provider_config_key": "<string>",
  "provider": "<string>",
  "errors": [
    {
      "type": "auth",
      "log_id": "VrnbtykXJFckCm3HP93t"
    }
  ],
  "metadata": {},
  "connection_config": {},
  "tags": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "last_fetched_at": "<string>",
  "credentials": {
    "oauth_token": "<string>",
    "oauth_token_secret": "<string>",
    "type": "OAUTH1",
    "raw": {}
  },
  "end_user": {
    "id": "<string>",
    "email": "<string>",
    "display_name": "<string>",
    "tags": {},
    "organization": {
      "id": "<string>",
      "display_name": "<string>"
    }
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "errors": [
      {}
    ]
  }
}

POST

connections

Upsert a connection

curl --request POST \
  --url https://api.nango.dev/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider_config_key": "<string>",
  "credentials": {
    "oauth_token": "<string>",
    "oauth_token_secret": "<string>",
    "type": "OAUTH1"
  },
  "metadata": {},
  "connection_id": "<string>",
  "connection_config": {},
  "tags": {}
}
'

import requests

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

payload = {
    "provider_config_key": "<string>",
    "credentials": {
        "oauth_token": "<string>",
        "oauth_token_secret": "<string>",
        "type": "OAUTH1"
    },
    "metadata": {},
    "connection_id": "<string>",
    "connection_config": {},
    "tags": {}
}
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({
    provider_config_key: '<string>',
    credentials: {oauth_token: '<string>', oauth_token_secret: '<string>', type: 'OAUTH1'},
    metadata: {},
    connection_id: '<string>',
    connection_config: {},
    tags: {}
  })
};

fetch('https://api.nango.dev/connections', 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/connections",
  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([
    'provider_config_key' => '<string>',
    'credentials' => [
        'oauth_token' => '<string>',
        'oauth_token_secret' => '<string>',
        'type' => 'OAUTH1'
    ],
    'metadata' => [
        
    ],
    'connection_id' => '<string>',
    'connection_config' => [
        
    ],
    'tags' => [
        
    ]
  ]),
  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/connections"

	payload := strings.NewReader("{\n  \"provider_config_key\": \"<string>\",\n  \"credentials\": {\n    \"oauth_token\": \"<string>\",\n    \"oauth_token_secret\": \"<string>\",\n    \"type\": \"OAUTH1\"\n  },\n  \"metadata\": {},\n  \"connection_id\": \"<string>\",\n  \"connection_config\": {},\n  \"tags\": {}\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/connections")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider_config_key\": \"<string>\",\n  \"credentials\": {\n    \"oauth_token\": \"<string>\",\n    \"oauth_token_secret\": \"<string>\",\n    \"type\": \"OAUTH1\"\n  },\n  \"metadata\": {},\n  \"connection_id\": \"<string>\",\n  \"connection_config\": {},\n  \"tags\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"provider_config_key\": \"<string>\",\n  \"credentials\": {\n    \"oauth_token\": \"<string>\",\n    \"oauth_token_secret\": \"<string>\",\n    \"type\": \"OAUTH1\"\n  },\n  \"metadata\": {},\n  \"connection_id\": \"<string>\",\n  \"connection_config\": {},\n  \"tags\": {}\n}"

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

{
  "id": 123,
  "connection_id": "<string>",
  "provider_config_key": "<string>",
  "provider": "<string>",
  "errors": [
    {
      "type": "auth",
      "log_id": "VrnbtykXJFckCm3HP93t"
    }
  ],
  "metadata": {},
  "connection_config": {},
  "tags": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "last_fetched_at": "<string>",
  "credentials": {
    "oauth_token": "<string>",
    "oauth_token_secret": "<string>",
    "type": "OAUTH1",
    "raw": {}
  },
  "end_user": {
    "id": "<string>",
    "email": "<string>",
    "display_name": "<string>",
    "tags": {},
    "organization": {
      "id": "<string>",
      "display_name": "<string>"
    }
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "errors": [
      {}
    ]
  }
}

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

When to use

Use this API endpoint to import existing access tokens into Nango. It is mostly meant for one-off bulk imports when onboarding Nango, or for migrating existing connections when a provider introduced changes to its auth flow. If a connection with the same connection_id and provider_config_key already exists, the endpoint updates it with the provided credentials instead of creating a new one. To trigger OAuth flows with Nango, use the Nango frontend SDK.

Request body

You can use this endpoint to import OAuth 2, OAuth 1, API Keys, and Basic auth credentials. The required fields depend on the type of authentication of the connections you are trying to import.

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

provider_config_key

string

required

The integration ID that you created on Nango.

credentials

OAuth1 · object

required

The credentials to be attached to the connection.

Show child attributes

metadata

object

(OAuth, required for some APIs) Metadata to be attached to the connection.

connection_id

string

The connection ID used to create the connection.

connection_config

object

(OAuth, required for some APIs) Additional configuration to be attached to the connection.

Response

Successfully created an integrations

integer

required

connection_id

string

required

provider_config_key

string

required

provider

string

required

errors

object[]

required

Show child attributes

metadata

object

required

connection_config

object

required

Getting started

Guides

Reference

When to use

Request body

Authorizations

Body

Response