Connect UI

Embed a white-label authorization flow directly in your product using Nango’s pre-built Connect UI or a shareable connect link.

What is the Connect UI?

The Connect UI is a Nango-hosted interface that handles the entire authorization flow for your users. It opens as a full-screen iframe in your product and guides users through OAuth logins, API key entry, and provider-specific configuration — without any custom UI code from you.

It is white-labeled: it shows provider logos and names, but no Nango branding. You can customize the theme, language, and which integrations are available.

Install the frontend SDK

npm install @nangohq/frontend

Initialize and open the Connect UI

import Nango from '@nangohq/frontend';

const nango = new Nango();

const connect = nango.openConnectUI({
  onEvent: (event) => {
    if (event.type === 'connect') {
      // Authorization succeeded.
      console.log('Connection ID:', event.payload.connectionId);
      console.log('Integration:', event.payload.providerConfigKey);
    } else if (event.type === 'close') {
      // User closed the UI without completing auth.
    } else if (event.type === 'error') {
      // Authorization failed.
      console.error(event.payload.errorType, event.payload.errorMessage);
    }
  },
});

// Fetch a session token from your backend and pass it to the UI.
const res = await fetch('/session-token', { method: 'POST' });
const { sessionToken } = await res.json();
connect.setSessionToken(sessionToken);

The openConnectUI() call immediately renders the iframe. A loading indicator is shown until you call setSessionToken(). Separating the two calls lets you open the UI optimistically while your backend request is in flight.

Event types

The onEvent callback receives events from the Connect UI:

Event type	Payload	Description
ready	—	The iframe has loaded and is ready to receive the session token.
connect	{ connectionId, providerConfigKey }	Authorization succeeded. A new connection has been created.
close	—	The user closed the UI. This does not indicate success or failure.
error	{ errorType, errorMessage }	Authorization failed.
settings_changed	ConnectUISettings	The user changed a setting inside the UI (for example, theme).

Customization options

Pass options to openConnectUI() to control the UI behavior:

nango.openConnectUI({
  onEvent: (event) => { /* ... */ },

  // Override the display language (defaults to the user's browser language).
  lang: 'fr',

  // Override the color theme ('light', 'dark', or 'system').
  themeOverride: 'dark',

  // If true, a closed OAuth popup is treated as a failed authorization.
  detectClosedAuthWindow: true,
});

To control which integrations are shown, pass allowed_integrations when creating the session token on your backend:

// Show a list of integrations for the user to choose from.
await nango.createConnectSession({
  tags: { end_user_id: '<END-USER-ID>' },
  allowed_integrations: ['github', 'slack', 'salesforce']
});

// Send the user directly to one integration's flow.
await nango.createConnectSession({
  tags: { end_user_id: '<END-USER-ID>' },
  allowed_integrations: ['github']
});

Close the UI programmatically

The openConnectUI() method returns a ConnectUI instance. Call .close() on it to dismiss the UI from your code:

const connect = nango.openConnectUI({ onEvent: (event) => { /* ... */ } });

// Later, close the UI programmatically.
connect.close();

The UI also closes automatically when the user completes or cancels the flow.

Use a custom auth UI instead of Connect UI

If you need full control over the authorization UX — for example, to build a custom API key entry form — you can use nango.auth() directly instead of openConnectUI(). Initialize the SDK with the session token first:

import Nango from '@nangohq/frontend';

const nango = new Nango({ connectSessionToken: '<CONNECT-SESSION-TOKEN>' });

Then call nango.auth() with the appropriate credentials for the auth type:

OAuth

nango
  .auth('<INTEGRATION-ID>')
  .then((result) => {
    // Show success UI.
  })
  .catch((error) => {
    // Show failure UI.
  });

API key

nango
  .auth('<INTEGRATION-ID>', {
    credentials: {
      apiKey: '<END-USER-API-KEY>'
    }
  })
  .then((result) => {
    // Show success UI.
  })
  .catch((error) => {
    // Show failure UI.
  });

Basic auth

nango
  .auth('<INTEGRATION-ID>', {
    credentials: {
      username: '<END-USER-USERNAME>',
      password: '<END-USER-PASSWORD>'
    }
  })
  .then((result) => {
    // Show success UI.
  })
  .catch((error) => {
    // Show failure UI.
  });

For APIs that require connection-specific configuration (such as a Zendesk subdomain), pass it in params:

nango.auth('zendesk', {
  params: { subdomain: '<ZENDESK-SUBDOMAIN>' }
});

To override scopes at the connection level:

nango.auth('zendesk', {
  params: { oauth_scopes_override: 'read:contacts write:contacts' }
});

Share a connect link

A connect link lets you trigger authorization without embedding the Connect UI in your product. This is useful for email-based onboarding, support-assisted setup, or cross-device flows.

Generate a connect link from your backend:

TypeScript

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

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

app.post('/connect-link', async (req, res) => {
  const { data } = await nango.createConnectSession({
    tags: {
      end_user_id: '<END-USER-ID>',
      end_user_email: '<END-USER-EMAIL>',
      organization_id: '<ORGANIZATION-ID>'
    },
    allowed_integrations: ['<INTEGRATION-ID>']
  });

  res.status(200).json({
    connectLink: data.connect_link,
    expiresAt: data.expires_at
  });
});

cURL

curl --request POST \
  --url https://api.nango.dev/connect/sessions \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": {
      "end_user_id": "<END-USER-ID>",
      "end_user_email": "<END-USER-EMAIL>",
      "organization_id": "<ORGANIZATION-ID>"
    },
    "allowed_integrations": ["<INTEGRATION-ID>"]
  }'

The returned connect_link is a short-lived URL that expires after 30 minutes. Send it to the user via email, Slack, or any other channel.

Generate a connect link from the dashboard:

Open the Connections page in the Nango dashboard and use the Share connect link button to generate a link without writing any code.

Next steps

Implement auth

Full guide to setting up the authorization flow end to end.

Connection management

List, retrieve, and manage connections after they are created.