Frontend SDK

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

Instantiate the frontend SDKCopy Anchor Link

import Nango from '@nangohq/frontend';

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

Parameters

Connect using Tenklo Connect UICopy Anchor Link

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

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

Parameters

Response

Connect using the headless clientCopy Anchor Link

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

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

Parameters

Success response

Error response

Error HandlingCopy Anchor Link

The Tenklo 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. 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)."

2. blocked_by_browser

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

3. invalid_host_url

   • Occurs when the provided host URL is invalid.
   • Message: "Invalid URL provided for the Tenklo host."

4. missing_credentials

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

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

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 functions enabled"

9. 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 StructureCopy Anchor Link

All errors from the Tenklo Frontend SDK follow this structure:

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

Handling ErrorsCopy Anchor Link

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