Migrate from Nango

Move an agent from Nango to AgentKit: map Nango integrations and connections, export credentials and import them, and update your tool calls.

Use this page if your agent uses Nango today. It covers what’s specific to Nango: how its concepts map to AgentKit, how to export your users’ credentials and import them, and how your tool calls change. The steps every migration shares, such as setting up Scalekit and creating connections, are in Migrate to AgentKit.

How Nango maps to AgentKit

Nango	AgentKit
Integration (integration ID, `provider_config_key`)	Connection, referred to by its connection name
Connection (`connection_id`)	Connected account: one per user and connection
`end_user_id` tag	Identifier: your app’s ID for the user, passed on each call
Connect UI and connect session	Authorization link
Tools and actions you write	Connector tools, or custom tools that call the API through the proxy
Proxy (`nango.proxy()`, `nango.get()`)	`actions.request()` through the Scalekit proxy
Agent sessions over MCP	Virtual MCP server with a session token per agent run

Move your users

Nango returns a connection’s stored credentials, so you can import them and your users don’t have to connect again. That works when:

OAuth: the Nango integration uses your own OAuth app. Create the Scalekit connection with the same client ID and secret; see Bring your own OAuth app. A refresh token works only with the OAuth app that issued it, so users of an integration on a Nango-managed OAuth app authorize again.
API keys and basic auth: always.
Your Nango secret key has the environment:connections:read_credentials scope. Without it, Nango leaves the credentials out of the response.

The script below lists the Nango connections of each integration, reads each one’s credentials and creates a connected account in Scalekit. It uses each connection’s end_user_id tag as the Scalekit identifier. If you keep your user ID somewhere else, such as in the connection’s metadata, change that line.

Add your Nango secret key to the .env file from Set up Scalekit:

NANGO_SECRET_KEY=your_nango_secret_key

Python
Node.js

Install requests too: pip install scalekit-sdk-python python-dotenv requests. The script needs Python 3.11 or later.

1
import os
2
from datetime import datetime
3

4
import requests
5
from dotenv import load_dotenv
6
from scalekit import ScalekitClient
7
from scalekit.common.exceptions import ScalekitServerException
8

9
load_dotenv()
10
scalekit_client = ScalekitClient(
11
    os.environ["SCALEKIT_ENVIRONMENT_URL"],
12
    os.environ["SCALEKIT_CLIENT_ID"],
13
    os.environ["SCALEKIT_CLIENT_SECRET"],
14
)
15
actions = scalekit_client.actions
16

17
NANGO_URL = "https://api.nango.dev"
18
NANGO_HEADERS = {"Authorization": f"Bearer {os.environ['NANGO_SECRET_KEY']}"}
19

20
# Your Nango integration ID -> (Scalekit connection name, field for an API key)
21
CONNECTIONS = {
22
    "google-mail": ("gmail", None),  # OAuth
23
    "openai": ("openai", "token"),  # API key, sent as a bearer token
24
    "twilio": ("twilio", None),  # basic auth
25
}
26

27

28
def to_authorization_details(credentials, key_field):
29
    kind = credentials["type"]
30
    if kind == "OAUTH2":
31
        token = {"access_token": credentials["access_token"]}
32
        if credentials.get("refresh_token"):
33
            token["refresh_token"] = credentials["refresh_token"]
34
        if credentials.get("expires_at"):
35
            token["expires_at"] = datetime.fromisoformat(credentials["expires_at"])
36
        return {"oauth_token": token}
37
    if kind == "API_KEY" and key_field:
38
        return {"static_auth": {key_field: credentials["apiKey"]}}
39
    if kind == "BASIC":
40
        return {"static_auth": {"username": credentials["username"], "password": credentials["password"]}}
41
    return None
42

43

44
for integration_id, (connection_name, key_field) in CONNECTIONS.items():
45
    page = 0
46
    while True:
47
        listed = requests.get(
48
            f"{NANGO_URL}/connections",
49
            headers=NANGO_HEADERS,
50
            params={"integrationId": integration_id, "limit": 1000, "page": page},
51
        )
52
        listed.raise_for_status()
53
        connections = listed.json()["connections"]
54

55
        for connection in connections:
56
            identifier = (connection.get("tags") or {}).get("end_user_id")
57
            if not identifier:
58
                print("skipped, no end_user_id tag:", connection["connection_id"])
59
                continue
60

61
            full = requests.get(
62
                f"{NANGO_URL}/connections/{connection['connection_id']}",
63
                headers=NANGO_HEADERS,
64
                params={"provider_config_key": integration_id, "refresh_token": "true"},
65
            )
66
            full.raise_for_status()
67
            details = to_authorization_details(full.json()["credentials"], key_field)
68
            if details is None:
69
                print("skipped, credential type not mapped:", connection["connection_id"])
70
                continue
71

72
            try:
73
                created = actions.create_connected_account(
74
                    connection_name=connection_name,
75
                    identifier=identifier,
76
                    authorization_details=details,
77
                )
78
                print(connection_name, identifier, created.connected_account.status)
79
            except ScalekitServerException as e:
80
                print(connection_name, identifier, "failed:", e.error_code, e.message)
81

82
        if len(connections) < 1000:
83
            break
84
        page += 1

Save the code in a .mts file, such as migrate-nango.mts, and run it with npx tsx migrate-nango.mts. It needs Node.js 18 or later, for fetch.

1
import 'dotenv/config';
2
import { ScalekitClient, ScalekitServerException, ConnectorStatus } from '@scalekit-sdk/node';
3
import { timestampFromDate } from '@bufbuild/protobuf/wkt';
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL!,
7
  process.env.SCALEKIT_CLIENT_ID!,
8
  process.env.SCALEKIT_CLIENT_SECRET!,
9
);
10
const actions = scalekit.actions;
11

12
const NANGO_URL = 'https://api.nango.dev';
13
const nangoHeaders = { Authorization: `Bearer ${process.env.NANGO_SECRET_KEY}` };
14

15
// Your Nango integration ID -> Scalekit connection name, and the field for an API key
16
const CONNECTIONS: Record<string, { connectionName: string; keyField?: string }> = {
17
  'google-mail': { connectionName: 'gmail' }, // OAuth
18
  openai: { connectionName: 'openai', keyField: 'token' }, // API key, sent as a bearer token
19
  twilio: { connectionName: 'twilio' }, // basic auth
20
};
21

22
async function nango(path: string, params: Record<string, string>) {
23
  const res = await fetch(`${NANGO_URL}${path}?${new URLSearchParams(params)}`, { headers: nangoHeaders });
24
  if (!res.ok) throw new Error(`Nango ${path}: ${res.status} ${await res.text()}`);
25
  return res.json();
26
}
27

28
function toAuthorizationDetails(credentials: any, keyField?: string) {
29
  if (credentials.type === 'OAUTH2') {
30
    return {
31
      details: {
32
        case: 'oauthToken' as const,
33
        value: {
34
          accessToken: credentials.access_token,
35
          refreshToken: credentials.refresh_token,
36
          expiresAt: credentials.expires_at ? timestampFromDate(new Date(credentials.expires_at)) : undefined,
37
        },
38
      },
39
    };
40
  }
41
  if (credentials.type === 'API_KEY' && keyField) {
42
    return { details: { case: 'staticAuth' as const, value: { details: { [keyField]: credentials.apiKey } } } };
43
  }
44
  if (credentials.type === 'BASIC') {
45
    const fields = { username: credentials.username, password: credentials.password };
46
    return { details: { case: 'staticAuth' as const, value: { details: fields } } };
47
  }
48
  return undefined;
49
}
50

51
for (const [integrationId, { connectionName, keyField }] of Object.entries(CONNECTIONS)) {
52
  for (let page = 0; ; page++) {
53
    const { connections } = await nango('/connections', {
54
      integrationId,
55
      limit: '1000',
56
      page: String(page),
57
    });
58

59
    for (const connection of connections) {
60
      const identifier = connection.tags?.end_user_id;
61
      if (!identifier) {
62
        console.log('skipped, no end_user_id tag:', connection.connection_id);
63
        continue;
64
      }
65

66
      const full = await nango(`/connections/${connection.connection_id}`, {
67
        provider_config_key: integrationId,
68
        refresh_token: 'true',
69
      });
70
      const authorizationDetails = toAuthorizationDetails(full.credentials, keyField);
71
      if (!authorizationDetails) {
72
        console.log('skipped, credential type not mapped:', connection.connection_id);
73
        continue;
74
      }
75

76
      try {
77
        const created = await actions.createConnectedAccount({ connectionName, identifier, authorizationDetails });
78
        console.log(connectionName, identifier, created.connectedAccount && ConnectorStatus[created.connectedAccount.status]);
79
      } catch (err) {
80
        if (!(err instanceof ScalekitServerException)) throw err;
81
        console.log(connectionName, identifier, 'failed:', err.errorCode, err.message);
82
      }
83
    }
84

85
    if (connections.length < 1000) break;
86
  }
87
}

Each imported account comes back ACTIVE. Change CONNECTIONS to your own integration IDs and connection names. For an API key, the field name depends on the Scalekit connector: OpenAI takes a bearer token, Exa takes api_key. See API keys, bearer tokens and basic auth for how to list a connector’s fields.

If a connection already exists for a user, for example because you ran the script twice, creating it again fails and the script prints the error. To replace the credential, use update_connected_account instead.

Move your agent code

Tools

Nango tools and actions are functions you wrote and deployed to Nango. In AgentKit, use the connector’s built-in tools where one does the same job, and move the rest into your app as custom tools that call the API through the Scalekit proxy.

Before (Nango, Node.js):

const result = await nango.callTool(
  { connectionId: '<CONNECTION-ID>', name: 'create-issue' },
  { input: { owner: 'acme', repo: 'agent', title: 'Bug report' } },
);

After (Scalekit):

Python
Node.js

result = actions.execute_tool(
    tool_name="github_issue_create",
    identifier="user_123",
    connection_name="github",
    tool_input={"owner": "acme", "repo": "agent", "title": "Bug report"},
)
print(result.data)

const result = await actions.executeTool({
  toolName: 'github_issue_create',
  identifier: 'user_123',
  connector: 'github',
  toolInput: { owner: 'acme', repo: 'agent', title: 'Bug report' },
});
console.log(result.data);

Nango addresses a user’s account by connectionId. AgentKit addresses it by your user’s identifier plus the connection name, so you don’t need to store a connection ID per user.

Proxy

Before (Nango, Node.js):

const response = await nango.get({
  endpoint: '/gmail/v1/users/me/messages',
  providerConfigKey: 'google-mail',
  connectionId: '<CONNECTION-ID>',
});

After (Scalekit):

Python
Node.js

response = actions.request(
    connection_name="gmail",
    identifier="user_123",
    method="GET",
    path="/gmail/v1/users/me/messages",
)

const response = await actions.request({
  connectionName: 'gmail',
  identifier: 'user_123',
  method: 'GET',
  path: '/gmail/v1/users/me/messages',
});

MCP

If your agent used a Nango agent session’s MCP URL, create a Virtual MCP server with the same connections and tools. It has one static URL for all users; mint a session token for the user before each agent run and pass it as a bearer token.

Migrate to AgentKitThe steps every migration shares, including the import fields.

Custom toolsMove your own Nango functions into your app.

API reference

The endpoints this page's code calls, with every field and the SDK method for each:

POSTCreate a connected account
POSTExecute a tool