frontend.mdx

title	sidebarTitle	icon
Frontend SDK reference	Frontend SDK	js

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

let nango = new Nango({ publicKey: '<PUBLIC-KEY>' });

Parameters

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

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

Collect & store end-user credentials

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

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

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

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

The connection ID that you can find in the _Connections_ tab on the Nango UI. Specify additional [connection configuration](/integrate/guides/authorize-an-api#apis-requiring-connection-specific-configuration-for-authorization) necessary to perform the authorization request.

  <ResponseField name="hmac" type="string">
    HMAC key to secure the authorization flow (cf. (instructions)[TODO]).
  </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>
    </Expandable>
  </ResponseField>
</Expandable>

Success response

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

Error response The type of error (e.g. 'authorization_cancelled').

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

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