Frontend

The frontend SDK lets users authorize integrations in your frontend. It is available on NPM as @nangohq/frontend.

Initiating Nango

Nango Cloud

Get your Public Key from the Project Settings page.

import Nango from '@nangohq/frontend';

let nango = new Nango({ publicKey: '<PUBLIC-KEY>' });

Localhost

import Nango from '@nangohq/frontend';

let nango = new Nango({ host: 'http://localhost:3003', publicKey: '<PUBLIC-KEY>' });

Self-hosted

import Nango from '@nangohq/frontend';

let nango = new Nango({ host: '<INSTANCE-URL>', publicKey: '<PUBLIC-KEY>' });

If you have configured your self-hosted instance to use a custom websockets path, you will also need to set the websocketsPath configuration option:

import Nango from '@nangohq/frontend';

let nango = new Nango({ host: '<INSTANCE-URL>', publicKey: '<PUBLIC-KEY>', websocketsPath: '/<YOUR-WEBSOCKETS-PATH>' });

Collecting & storing end-user credentials

You store end-user credentials with the nango.auth method.

OAuth

For OAuth, the nango.auth() method will trigger the OAuth flow in a popup, to let the user log in to their external account.

nango
    .auth('<INTEGRATION-ID>', '<CONNECTION-ID>')
    .then((result) => {
        // result is an object with:
        // {
        //      providerConfigKey: '<INTEGRATION-ID>',
        //      connectionId: '<CONNECTION-ID>
        // }
    })
    .catch((error) => {
        // Error is an object with:
        // {
        //    error: {
        //      type: 'authorization_cancelled', (or similar)
        //      message: 'Authorization fail: The user has closed the authorization modal before the process was complete.'  (or similar)
        //    }
        // }
    });

API Key

For API keys, the nango.auth() method is used to store the end-user’s API key (that you have previously collected from them).

nango
    .auth('<INTEGRATION-ID>', '<CONNECTION-ID>', {
        credentials: {
            apiKey: '<END-USER-API-KEY>'
        }
    })
    .then((result) => {
        // result is an object with:
        // {
        //      providerConfigKey: '<INTEGRATION-ID>',
        //      connectionId: '<CONNECTION-ID>
        // }
    })
    .catch((error) => {
        // Error is an object with:
        // {
        //    error: {
        //      type: 'authorization_cancelled', (or similar)
        //      message: 'Authorization fail: The user has closed the authorization modal before the process was complete.'  (or similar)
        //    }
        // }
    });

Basic Auth

For Basic Auth, the nango.auth() method is used to store the end-user’s username & password (that you have previously collected from them).

nango
    .auth('<INTEGRATION-ID>', '<CONNECTION-ID>', {
        credentials: {
            username: '<END-USER-API-KEY>',
            password: '<END-USER-PASSWORD>'
        }
    })
    .then((result) => {
        // result is an object with:
        // {
        //      providerConfigKey: '<INTEGRATION-ID>',
        //      connectionId: '<CONNECTION-ID>
        // }
    })
    .catch((error) => {
        // Error is an object with:
        // {
        //    error: {
        //      type: 'authorization_cancelled', (or similar)
        //      message: 'Authorization fail: The user has closed the authorization modal before the process was complete.'  (or similar)
        //    }
        // }
    });

OAuth flows requiring extra configuration

Some API Providers require some connection-specific configuration (e.g. Zendesk, Shopify).

For example, Zendesk has the following authorization URL, where the subdomain is specific to a user’s Zendesk account:

https://<USER-SUBDOMAIN>.zendesk.com/oauth/authorizations/new

To set the subdomain pass in an additional configuration object to nango.auth():

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

Detect closed authorization page

To fail when the authorization window is closed before the authorization flow is completed pass in the extra parameter detectClosedAuthWindow to nango.auth()

nango.auth('zendesk', '<CONNECTION-ID>', {
     detectClosedAuthWindow: true,
     ...
});