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

<Expandable>
  <ResponseField name="config" type="object" required>
    <Expandable title="options" defaultOpen>
      <ResponseField name="publicKey" type="string" deprecated>
        Get your public key in the environment settings of the Nango UI. This is key is not sensitive.
      </ResponseField>

      <ResponseField name="host" type="string">
        Omitting the host points to Nango Cloud. For local development, use `http://localhost:3003`. Use your instance URL if self-hosting.
      </ResponseField>

      <ResponseField name="websocketsPath" type="string">
        For self-hosted instances only to specify a customs path for the WebSocket connection.
      </ResponseField>

      <ResponseField name="width" type="number">
        Specify a specific width for the OAuth authorization modal.
      </ResponseField>

      <ResponseField name="height" type="number">
        Specify a specific height for the OAuth authorization modal.
      </ResponseField>

      <ResponseField name="debug" type="boolean">
        Print additional console logs to debug authorization issues.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

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

<Expandable>
  <ResponseField name="sessionToken" type="string">
    The unique token to identify your user. It is required but can be set asynchronously.
  </ResponseField>

  <ResponseField name="baseURL" type="string" default="https://connect.nango.dev">
    The base URL to load the UI
  </ResponseField>

  <ResponseField name="apiURL" type="string" default="https://api.nango.dev">
    The base URL to reach Nango API
  </ResponseField>

  <ResponseField name="onEvent" type="function">
    A callback to listen to events sent by Nango Connect
  </ResponseField>

  <ResponseField name="detectClosedAuthWindow" type="boolean" default="false">
    Control OAuth popup close detection. If set to true, a closed popup will be detected as a failed authorization.
  </ResponseField>

  <ResponseField name="lang" type="string">
    The language to use for the UI. Defaults to browser language or english if not supported.
  </ResponseField>

  <ResponseField name="themeOverride" type="string">
    The theme (light, dark, system) to use for the UI. Overrides your global setting in the dashboard.
  </ResponseField>
</Expandable>

**Response**

<Expandable>
  <ResponseField name="connectUI" type="ConnectUI">
    The class to manipulate Nango Connect
  </ResponseField>
</Expandable>

# Connect using the headless client

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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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) => {
        ...
    });
    ```
  </Tab>
</Tabs>

**Parameters**

<Expandable>
  <ResponseField name="providerConfigKey" type="string" required>
    The integration ID that you can find in the integration settings on the Nango UI.
  </ResponseField>

  <ResponseField name="connectionId" type="string">
    The connection ID that you can find in the *Connections* tab on the Nango UI.
  </ResponseField>

  <ResponseField name="options" type="object">
    <Expandable title="options" defaultOpen>
      <ResponseField name="params" type="object">
        Specify additional connection configuration necessary to perform the authorization request.
      </ResponseField>

      <ResponseField name="hmac" type="string" deprecated>
        HMAC key to secure the authorization flow
      </ResponseField>

      <ResponseField name="detectClosedAuthWindow" type="boolean">
        If `true`, `nango.auth()` would fail if the login window is closed before the authorization flow is completed.
      </ResponseField>

      <ResponseField name="authorization_params" type="object">
        For OAuth, specify the query parameters of the authorization URL.
      </ResponseField>

      <ResponseField name="user_scope" type="string[]">
        For Slack OAuth, specify user-specific scopes.
      </ResponseField>

      <ResponseField name="credentials" type="object">
        <Expandable title="credentials" defaultOpen>
          <ResponseField name="apiKey" type="string">
            For API key authorization, pass in the user's API key.
          </ResponseField>

          <ResponseField name="username" type="string">
            For Basic authorization, pass in the user's username.
          </ResponseField>

          <ResponseField name="password" type="string">
            For Basic authorization, pass in the user's password.
          </ResponseField>

          <ResponseField name="oauth_client_id_override" type="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).
          </ResponseField>

          <ResponseField name="oauth_client_secret_override" type="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).
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

**Success response**

<Expandable>
  <ResponseField name="providerConfigKey" type="string">
    The integration ID that you can find in the integration settings on the Nango UI.
  </ResponseField>

  <ResponseField name="connectionId" type="string">
    The connection ID that you can find in the *Connections* tab on the Nango UI.
  </ResponseField>
</Expandable>

**Error response**

<Expandable>
  <ResponseField name="error" type="object">
    <Expandable title="error" defaultOpen>
      <ResponseField name="type" type="string">
        The type of error (e.g. 'authorization\_cancelled').
      </ResponseField>

      <ResponseField name="message" type="string">
        The detailed error message (e.g. 'Authorization fail: The user has closed the authorization modal before the process was complete.').
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

# 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).
</Tip>