Core concepts

// List all available providers
const { providers } = await nango.listProviders({});

// Retrieve an integration
const integration = await nango.getIntegration({ uniqueKey: 'github' });

// Create an integration programmatically
await nango.createIntegration({
  provider: 'github',
  unique_key: 'github',
  display_name: 'GitHub'
});

// Retrieve a connection and its credentials
const connection = await nango.getConnection('github', 'user-123');
console.log(connection.credentials);
// { type: 'OAUTH2', access_token: 'gho_...', expires_at: '...' }

// List all connections for an integration
const { connections } = await nango.listConnections({ integrationId: 'github' });

// Frontend: open Nango's managed Connect UI
import Nango from '@nangohq/frontend';

const nango = new Nango({ connectSessionToken: sessionToken });

nango.openConnectUI({
  onEvent: (event) => {
    if (event.type === 'close') {
      // Connection created — user is authorized
    }
  }
});

// Backend: create a session token before opening the UI
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });

const session = await nango.createConnectSession({
  end_user: { id: 'user-123', email: 'user@example.com' },
  allowed_integrations: ['github']
});

// Pass session.data.token to your frontend

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

const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });

// GET request
const contacts = await nango.get({
  endpoint: '/v3/contacts',
  providerConfigKey: 'hubspot',
  connectionId: 'user-123'
});

// POST request with a body
const issue = await nango.post({
  endpoint: '/repos/my-org/my-repo/issues',
  providerConfigKey: 'github',
  connectionId: 'user-123',
  data: { title: 'Bug report', body: 'Something went wrong.' }
});

// With retries and custom headers
const response = await nango.get({
  endpoint: '/messages',
  providerConfigKey: 'gmail',
  connectionId: 'user-123',
  retries: 3,
  headers: { 'X-Custom-Header': 'value' }
});

// A sync that fetches GitHub issues on a schedule
export default async function run(nango: NangoSync) {
  const response = await nango.get({
    endpoint: '/repos/my-org/my-repo/issues',
    params: { state: 'open', per_page: '100' }
  });

  await nango.batchSave(response.data, 'GitHubIssue');
}

// An action that creates a GitHub issue on demand
export default async function run(nango: NangoAction) {
  const { owner, repo, title, body } = nango.input;

  const response = await nango.post({
    endpoint: `/repos/${owner}/${repo}/issues`,
    data: { title, body }
  });

  return { id: response.data.id, url: response.data.html_url };
}

// Trigger the action from your backend
const result = await nango.triggerAction(
  'github',      // providerConfigKey
  'user-123',    // connectionId
  'create-issue',
  { owner: 'my-org', repo: 'my-repo', title: 'New issue', body: 'Details...' }
);