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
• API Key
• Basic Auth

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

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.