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

API Key

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

Basic Auth

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

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.

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.