Trigger authorization flows in your frontend with this SDK. It is available on NPM as @nangohq/frontend.

​

Instantiate the frontend SDK

import Nango from '@nangohq/frontend';

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

Parameters

​

Connect using Nango Connect UI

Nango provides a UI component that guides your app’s users through automatically and securely setting up an integration. This UI is hosted on Nango’s servers and requires minimal setup on your end to get started quickly. This is the recommended way to use Nango in your frontend.

const connectUI = nango.openConnectUI({ sessionToken: 'SESSION_TOKEN' });

Parameters

Response

​

Connect using the headless client

You store end-user credentials with the nango.auth method. It creates a connection in Nango.

const result = await nango.auth('<INTEGRATION-ID>').catch((error) => {
...
});

const result = await nango.auth('<INTEGRATION-ID>').catch((error) => {
...
});

const result = await nango.auth('<INTEGRATION-ID>', {
    credentials: { apiKey: '<END-USER-API-KEY>' }
}).catch((error) => {
    ...
});

const result = nango.auth('<INTEGRATION-ID>', {
    credentials: { username: '<END-USER-API-KEY>', password: '<END-USER-PASSWORD>' }
}).catch((error) => {
    ...
});

Parameters

Success response

Error response

​

Error Handling

The Nango Frontend SDK may throw different types of errors during authentication and connection setup. Below is a list of all possible error types along with their meanings:

1. missingAuthToken

   • Occurs when neither a public key nor a connect session token is provided.
   • Message: “You must specify a public key OR a connect session token (cf. documentation).”

2. blocked_by_browser

   • Occurs when the browser blocks the popup window for authentication.
   • Message: “Modal blocked by browser”

3. invalidHostUrl

   • Occurs when the provided host URL is invalid.
   • Message: “Invalid URL provided for the Nango host.”

4. missingCredentials

   • Occurs when required credentials are not provided.
   • Message: “You must specify credentials.”

5. windowClosed

   • Occurs when the authentication window is closed before completing the flow.
   • Message: “The authorization window was closed before the authorization flow was completed”

6. connection_test_failed

   • Occurs when credential verification fails for certain integrations before the connection is established.
   • Message: “The given credentials were found to be invalid. Please check the credentials and try again.”

7. missing_connect_session_token

   • Occurs when attempting to reconnect without a session token.
   • Message: “Reconnect requires a session token”

8. resource_capped

   • Occurs when the resource usage limit has been reached.
   • Message: “Reached maximum number of allowed connections for your plan” or “Reached maximum number of connections with scripts enabled”

​

Error Response Structure

All errors from the Nango Frontend SDK follow this structure:

{
    "error": {
        "code": "<error_type>",
        "message": "<detailed_error_message>"
    }
}

​

Handling Errors

You can handle these errors in your code using the AuthError class.

import { AuthError } from '@nangohq/frontend';

try {
    const result = await nango.auth('<INTEGRATION-ID>', {
        credentials: { apiKey: '<END-USER-API-KEY>' }
    });
} catch (error) {
    if (error instanceof AuthError && error.type === '<error_type>') {
        // Handle specific error
        console.error('Your error message');
    }
}