Connect UI

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
API key
Basic auth

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

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

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' }
});

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
cURL

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 --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.

Get Started

Auth

Functions

Use Cases

Platform

What is the Connect UI?

Install the frontend SDK

Initialize and open the Connect UI

Event types

Customization options

Close the UI programmatically

Use a custom auth UI instead of Connect UI

Next steps

Implement auth

Connection management

​What is the Connect UI?

​Install the frontend SDK

​Initialize and open the Connect UI

​Event types

​Customization options

​Close the UI programmatically

​Use a custom auth UI instead of Connect UI

​Share a connect link

​Next steps

Implement auth

Connection management

What is the Connect UI?

Install the frontend SDK

Initialize and open the Connect UI

Event types

Customization options

Close the UI programmatically

Use a custom auth UI instead of Connect UI

Share a connect link

Next steps