> ## 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.

# Frontend SDK

Trigger authorization flows in your frontend with this SDK. It is available on [NPM](https://www.npmjs.com/package/@nangohq/frontend) as `@nangohq/frontend`.

## Instantiate the frontend SDK

```ts theme={null}
import Nango from '@nangohq/frontend';

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

**Parameters**

**config** `object` *required*

**options**

**publicKey** `string` *deprecated*

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

**host** `string`

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

**websocketsPath** `string`

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

**width** `number`

Specify a specific width for the OAuth authorization modal.

**height** `number`

Specify a specific height for the OAuth authorization modal.

**debug** `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.

```js theme={null}
const connectUI = nango.openConnectUI({ sessionToken: 'SESSION_TOKEN' });
```

**Parameters**

**sessionToken** `string`

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

**baseURL** `string` (default: [https://connect.nango.dev](https://connect.nango.dev))

The base URL to load the UI

**apiURL** `string` (default: [https://api.nango.dev](https://api.nango.dev))

The base URL to reach Nango API

**onEvent** `function`

A callback to listen to events sent by Nango Connect

**detectClosedAuthWindow** `boolean` (default: false)

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

**lang** `string`

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

**themeOverride** `string`

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

**Response**

**connectUI** `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.

> [tab] OAuth
>
> For OAuth, this will open a modal to let the user log in to their external account.
>
> ```js theme={null}
> const result = await nango.auth('<INTEGRATION-ID>').catch((error) => {
> ...
> });
> ```

> [tab] API Key
>
> For API key authorization, pass the end-user's previously-collected API key directly in the parameters.
>
> ```js theme={null}
> const result = await nango.auth('<INTEGRATION-ID>', {
>     credentials: { apiKey: '<END-USER-API-KEY>' }
> }).catch((error) => {
>     ...
> });
> ```

> [tab] Basic Auth
>
> For Basic Auth, pass the end-user's previously-collected username & password in the parameters.
>
> ```js theme={null}
> const result = nango.auth('<INTEGRATION-ID>', {
>     credentials: { username: '<END-USER-API-KEY>', password: '<END-USER-PASSWORD>' }
> }).catch((error) => {
>     ...
> });
> ```

**Parameters**

**providerConfigKey** `string` *required*

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

**connectionId** `string`

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

**options** `object`

**options**

**params** `object`

Specify additional connection configuration necessary to perform the authorization request.

**hmac** `string` *deprecated*

HMAC key to secure the authorization flow

**detectClosedAuthWindow** `boolean`

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

**authorization\_params** `object`

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

**user\_scope** `string[]`

For Slack OAuth, specify user-specific scopes.

**credentials** `object`

**credentials**

**apiKey** `string`

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

**username** `string`

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

**password** `string`

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

**oauth\_client\_id\_override** `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).

**oauth\_client\_secret\_override** `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**

**providerConfigKey** `string`

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

**connectionId** `string`

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

**Error response**

**error** `object`

**error**

**type** `string`

The type of error (e.g. 'authorization\_cancelled').

**message** `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:

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 Nango 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 Structure

All errors from the Nango Frontend SDK follow this structure:

```json theme={null}
{
    "error": {
        "code": "<error_type>",
        "message": "<detailed_error_message>"
    }
}
```

### Handling Errors

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

```ts theme={null}
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');
    }
}
```

> [!TIP]
>
> **Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.