Skip to main content

Documentation Index

Fetch the complete documentation index at: https://nango.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Pre-requisites:
Nango’s pre-built Connect UI is the recommended way to let users authorize integrations. It generates the right form for each API, validates required inputs, tests credentials when supported, and shows users where to find API keys or other required values. You can customize that pre-built UI with your own branding. If you need full control over every screen, you can also skip Connect UI and use Nango in a headless auth mode.

​
Customize the pre-built Connect UI

You can customize the Connect UI theme from the Nango dashboard:
  1. Open Environment Settings.
  2. Go to the Connect UI tab.
  3. Choose the theme: light, dark, or system.
  4. Set the primary color for the light theme.
  5. Set the primary color for the dark theme.
  6. Optionally remove the Secured by Nango mention.
These settings apply to the pre-built Connect UI that you open with nango.openConnectUI().
Connect UI branding customization is available on the Growth plan.
By default, the Connect UI displays info icons that link to the Nango documentation. If you are embedding Connect UI in a customer-facing application and want these links to point to your own documentation instead, override them per integration using the overrides parameter when creating a Connect session.
This feature is available on the Growth plan.
See the full SDK reference for all available parameters.
const { data } = await nango.createConnectSession({
    // Recommended: copied onto the connection and included in auth webhooks.
    tags: {
        end_user_id: '<END-USER-ID>',
        end_user_email: '<END-USER-EMAIL>',
        organization_id: '<ORGANIZATION-ID>'
    },

    allowed_integrations: ['<INTEGRATION-ID-1>', '<INTEGRATION-ID-2>'],
    integrations_config_defaults: {
        '<INTEGRATION-ID-1>': {
            connection_config: {
                '<CONFIG-KEY>': '<VALUE>'
            }
        }
    },
    overrides: {
        '<INTEGRATION-ID-1>': {
            docs_connect: 'https://your-docs.com/how-to-connect'
        }
    }
});
Replace <INTEGRATION-ID> with the unique name of the integration, for example jira or slack, and set docs_connect to the URL you want the info icons to link to.

​
Build your own auth UI

Headless auth means you build the user-facing setup UI yourself and use the frontend SDK to pass the required values to Nango. Headless auth still uses Nango for the backend parts of auth: Nango stores credentials, refreshes OAuth tokens, manages connection records, sends auth webhooks, and lets you call APIs through the proxy or from functions. What changes is the setup experience your user sees before the connection is created.

​
What changes with headless auth

For OAuth APIs, calling nango.auth() opens the external API’s login popup directly. Your user skips the Nango pre-authorization screen. This is useful when you want a shorter flow, but it also means you must collect any provider-specific inputs that the Nango Connect UI would normally ask for first. For API key, Basic Auth, and other non-OAuth flows, there is no external login popup. You must build the form that collects the user’s credentials, validate field formats in your own UI, and pass the credentials to nango.auth(). Nango can still reject invalid credentials when the integration supports credential checks, but your UI owns the input fields, error messages, and setup guidance. Some APIs also require connection configuration in addition to credentials. For example, an API might need a subdomain, domain, tenant ID, region, or account-specific base URL to build the authorization URL or make future API requests. Connect UI collects these fields automatically. With headless auth, your UI must collect them and pass them programmatically. See Connection tags, configuration, and metadata for the difference between connection configuration, metadata, and tags.

​
Use the frontend SDK for headless auth

In your frontend, initiate Nango (reference): 
import Nango from '@nangohq/frontend';

const nango = new Nango({ connectSessionToken: '<CONNECT-SESSION-TOKEN>' });
Then create the connection with nango.auth() (reference):
For OAuth, nango.auth() opens the external API’s login popup directly.
nango
    .auth('<INTEGRATION-ID>')
    .then((result) => {
        // Show success UI.
    })
    .catch((error) => {
        // Show failure UI.
    });

​
Pass connection configuration

Some APIs require connection-specific configuration to authorize or make API requests later. Zendesk is a common example: the OAuth authorization URL includes the user’s Zendesk subdomain: https://<USER-SUBDOMAIN>.zendesk.com/oauth/authorizations/new With Connect UI, Nango asks for this value in an automatically generated form. With headless auth, collect it in your own UI and pass it as params: 
nango.auth('zendesk', {
    params: { subdomain: '<ZENDESK-SUBDOMAIN>' }
});
You can also set default connection configuration when you create the Connect session. This is useful when your backend already knows a required value: 
const { data } = await nango.createConnectSession({
    allowed_integrations: ['<INTEGRATION-ID>'],
    integrations_config_defaults: {
        '<INTEGRATION-ID>': {
            connection_config: {
                '<CONFIG-KEY>': '<VALUE>'
            }
        }
    }
});
In some cases, you might want to override scopes at the connection level. Pass the scopes to nango.auth(): 
nango.auth('<INTEGRATION-ID>', {
    params: { oauth_scopes_override: 'custom-connection-scope' }
});
Nango stores this connection configuration on the connection. You can retrieve it with the SDK (reference) or API (reference), or see it in connection details in the Nango UI.

​
Next

Once authorization succeeds, save the connection ID.
Questions, problems, feedback? Please reach out in the Slack community.