Frontend SDK

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

Show child attributes

config · object · required

Hide options

publicKey · string · required

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.

Collect & store end-user credentials

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

OAuth

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) => {
...
});

Parameters

Show child attributes

providerConfigKey · string · required

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

connectionId · string · required

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

options · object

Hide options

params · object

Specify additional connection configuration necessary to perform the authorization request.

hmac · string

HMAC key to secure the authorization flow (cf. (instructions)[TODO]).

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

Hide 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

Show child attributes

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

Show child attributes

error · object

Hide 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.’).

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