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

Show child attributes

object

required

Hide options

string

deprecated

Get your public key in the environment settings of the Nango UI. This is key is not sensitive.

string

Omitting the host points to Nango Cloud. For local development, use http://localhost:3003. Use your instance URL if self-hosting.

string

For self-hosted instances only to specify a customs path for the WebSocket connection.

number

Specify a specific width for the OAuth authorization modal.

number

Specify a specific height for the OAuth authorization modal.

boolean

Print additional console logs to debug authorization issues.

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

Show child attributes

string

The unique token to identify your user. It is required but can be set asynchronously.

string

default:"https://connect.nango.dev"

The base URL to load the UI

string

default:"https://api.nango.dev"

The base URL to reach Nango API

function

A callback to listen to events sent by Nango Connect

boolean

default:"false"

Control OAuth popup close detection. If set to true, a closed popup will be detected as a failed authorization.

string

The language to use for the UI. Defaults to browser language or english if not supported.

string

The theme (light, dark, system) to use for the UI. Overrides your global setting in the dashboard.

Response

Show child attributes

ConnectUI

The class to manipulate Nango Connect

Connect using the headless client

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

OAuth
API Key
Basic Auth

For OAuth, this will open a modal to let the user log in to their external account.

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

For API key authorization, pass the end-user’s previously-collected API key directly in the parameters.

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

For Basic Auth, pass the end-user’s previously-collected username & password in the parameters.

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

Parameters

Show child attributes

string

required

The integration ID that you can find in the integration settings on the Nango UI.

string

The connection ID that you can find in the Connections tab on the Nango UI.

object

Hide options

object

Specify additional connection configuration necessary to perform the authorization request.

string

deprecated

HMAC key to secure the authorization flow

boolean

If true, nango.auth() would fail if the login window is closed before the authorization flow is completed.

object

For OAuth, specify the query parameters of the authorization URL.

string[]

For Slack OAuth, specify user-specific scopes.

object

Hide credentials

string

For API key authorization, pass in the user’s API key.

string

For Basic authorization, pass in the user’s username.

string

For Basic authorization, pass in the user’s password.

string

For OAuth 2, override the integration’s client ID with a connection-level client ID. This is useful when your users bring their own OAuth 2 app (e.g. Netsuite).

string

For OAuth 2, override the integration’s client secret with a connection-level client secret. This is useful when your users bring their own OAuth 2 app (e.g. Netsuite).

Success response

Show child attributes

string

The integration ID that you can find in the integration settings on the Nango UI.

string

The connection ID that you can find in the Connections tab on the Nango UI.

Error response

Show child attributes

object

Hide error

string

The type of error (e.g. ‘authorization_cancelled’).

string

The detailed error message (e.g. ‘Authorization fail: The user has closed the authorization modal before the process was complete.’).

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:

missing_auth_token
- 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).”
blocked_by_browser
- Occurs when the browser blocks the popup window for authentication.
- Message: “Modal blocked by browser”
invalid_host_url
- Occurs when the provided host URL is invalid.
- Message: “Invalid URL provided for the Nango host.”
missing_credentials
- Occurs when required credentials are not provided.
- Message: “You must specify credentials.”
window_closed
- Occurs when the authentication window is closed before completing the flow.
- Message: “The authorization window was closed before the authorization flow was completed”
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.”
missing_connect_session_token
- Occurs when attempting to reconnect without a session token.
- Message: “Reconnect requires a session token”
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 functions enabled”
unknown_error
- Occurs when an unexpected error happens that doesn’t fall into other error categories.
- Message: Varies depending on the underlying error (e.g., network failures, unexpected exceptions)

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

Questions, problems, feedback? Please reach out in the Slack community.

Getting started

Guides

Reference

Frontend SDK

Instantiate the frontend SDK

Connect using Nango Connect UI

Connect using the headless client

Error Handling

Error Response Structure

Handling Errors

​Instantiate the frontend SDK

​Connect using Nango Connect UI

​Connect using the headless client

​Error Handling

​Error Response Structure

​Handling Errors

Instantiate the frontend SDK

Connect using Nango Connect UI

Connect using the headless client

Error Handling

Error Response Structure

Handling Errors