API Auth with a custom UI

Guide to letting your users authorize an external API from your application, with your own UI.

Pre-requisites:

• complete the Configure an integration guide
• generate a Connect session token

Integrate the frontend SDK

In your frontend, initiate Nango (reference):

import Nango from '@nangohq/frontend';

const nango = new Nango({ connectSessionToken: '<CONNECT-SESSION-TOKEN>' });

Initiate the authorization flow (reference):

OAuth

For OAuth, the nango.auth() method will trigger the OAuth flow in a popup, to let the user log in to their external account.

nango
    .auth('<INTEGRATION-ID>')
    .then((result) => {
        // Show success UI.
    })
    .catch((error) => {
        // Show failure UI.
    });

API Key

For API keys, the nango.auth() method is used to store the end-user’s API key (that you have previously collected from them).

nango
    .auth('<INTEGRATION-ID>', {
        credentials: {
            apiKey: '<END-USER-API-KEY>'
        }
    })
    .then((result) => {
        // Show success UI.
    })
    .catch((error) => {
        // Show failure UI.
    });

Basic Auth

For Basic Auth, the nango.auth() method is used to store the end-user’s username & password (that you have previously collected from them).

nango
    .auth('<INTEGRATION-ID>', {
        credentials: {
            username: '<END-USER-API-KEY>',
            password: '<END-USER-PASSWORD>'
        }
    })
    .then((result) => {
        // Show success UI.
    })
    .catch((error) => {
        // Show failure UI.
    });

Handle APIs requiring connection-specific configuration for authorization

Some APIs require connection-specific configuration (e.g. Zendesk, Shopify).

For example, Zendesk has the following authorization URL, where the subdomain is specific to a user’s Zendesk account:

https://<USER-SUBDOMAIN>.zendesk.com/oauth/authorizations/new

When using the Connect UI, this information is collected from the end user with an automatically-generated form.

But when using a custom UI, you must provide this configuration when calling nango.auth() (reference):

nango.auth('zendesk', {
    params: { subdomain: '<ZENDESK-SUBDOMAIN>' }
});

In some cases you might want to override the scopes provided by an integration at the connection level. For this case you can pass in the scopes to nango.auth:

nango.auth('zendesk', {
    params: { oauth_scopes_override: 'custom-connection-scope' }
});

This connection configuration is stored in the connection. You can retrieve it with the SDK (reference) and API (reference), or see it in connection details in the Nango UI.

Override documentation links

By default, the Connect UI displays info icons that link to the Nango documentation. If you are embedding Connect in a customer-facing application and want these links to point to your own documentation instead, you can override them per integration using the overrides parameter when creating a Connect session.

This feature is available on the Growth plan.

Node SDK

See the full SDK reference for all available parameters.

const { data } = await nango.createConnectSession({
    // Recommended: copied onto the connection and included in auth webhooks.
    tags: {
        end_user_id: '<END-USER-ID>',
        end_user_email: '<END-USER-EMAIL>',
        organization_id: '<ORGANIZATION-ID>'
    },

    allowed_integrations: ['<INTEGRATION-ID-1>', '<INTEGRATION-ID-2>'],
    integrations_config_defaults: {
        '<INTEGRATION-ID-1>': {
            connection_config: {
                '<CONFIG-KEY>': '<VALUE>'
            }
        }
    },
    overrides: {
        '<INTEGRATION-ID-1>': {
            docs_connect: 'https://your-docs.com/how-to-connect'
        }
    }
});

REST API

See the full API reference for all available parameters.

curl --request POST \
  --url https://api.nango.dev/connect/sessions \
  --header 'Authorization: Bearer <SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": {
        "end_user_id": "<END-USER-ID>",
        "end_user_email": "<END-USER-EMAIL>"
    },
    "overrides": {
        "<INTEGRATION-ID>": {
            "docs_connect": "https://your-docs.com/how-to-connect"
        }
    }
}'

Replace <INTEGRATION-ID> with the unique name of the integration (e.g. jira, slack) and set docs_connect to the URL you want the info icons to link to.

Next

Once the authorization succeeds, save the connection ID.

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