​

Create a free Nango account

Sign up for a free Nango account (this feature is free & unlimited, no credit card needed):

​

Create an integration

Go to the Integrations tab, choose to configure a new integration, and choose an API to integrate with.

APIs have different ways to authorize requests: OAuth, API key, Basic, custom. Nango abstracts away the difficulties of working with each one.

For OAuth

OAuth APIs require you to register your OAuth application on their developer portal.

When registering, the API provider will prompt you for the Callback URL. Use the one displayed in the Nango integration settings. Remember to register the required scopes in the Nango integration settings and, if necessary, with the API provider.

Collect your OAuth app’s Client ID and Client Secret from the API portal and input them in your Nango integration settings.

For API Key & Basic

No configuration is necessary for APIs supporting API key & Basic authorization.

For Custom Authorization

APIs like Stripe & GitHub Apps have custom authorization. Configurations vary and are described in the Nango integration settings.

​

Test the authorization

On the Nango integration page, click Add Connection to test the authorization. After authorizing API access for one of the modes described below, a connection should be successfully created in the Connections tab.

For OAuth

Input your external account credentials in the popup dialog to test the authorization.

For API Key & Basic

Input the API key (or username/password for Basic) to test the authorization.

For Custom Authorization

The authorization flow will vary based on the API, but you will most likely have to log in to your external account via a popup dialog.

​

Authorize users from your app

Nango Connect requires a unique temporary token to securely authenticate your users.

​

Step 1: Generate a Session token

To securely authenticate your users, we need a dedicated token generated on your backend and passed to the frontend. This security measure allows us to strictly identify authenticated users and pre-filter allowed integrations.

On your backend, you need an API endpoint that your frontend contacts, which will then communicate with the Nango API. Once you get back the token, forward it to Nango Connect. This token has a lifespan of 30 minutes after which it expires.

import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env['NANGO_SECRET_KEY'] });

api.post('/sessionToken', (req, res) => {
  // Ask Nango for a secure token
  const res = await nango.createConnectSession({
    end_user: {
      id: user.id,
      email: user.email,
      display_name: user.displayName,
    },
    allowed_integrations: ['bamboohr'],
  });

  // Send this token back to your frontend
  res.status(200).send({
    sessionToken: res.data.token
  });
});

​

Step 2: Trigger Auth Flow

In your frontend, you need to load our SDK, get the Session Token from Step 1 and open Nango Connect

import Nango from '@nangohq/frontend';

const nango = new Nango();
const connect = nango.openConnectUI();

// Call the endpoint created in Step 1
const res = await fetch('/sessionToken', { method: 'POST' });
connect.setSessionToken(res.sessionToken);

​

Step 3: Link Connection ID to your user

In your frontend, the Connect UI will send back an event when a user connects or closes the modal. You can register an event listener and respond appropriately.

When a user completes a flow, you will receive a connect event. This event contains the providerConfigKey, which is the id of your integration and a connectionId, which is the auto-generated id that represents the couple user + integration.

[...]

function saveConnectionId(authResults) {
  await fetch('/connection', { method: 'POST', body: authResults });
}

nango.openConnectUI({
  sessionToken: await getSessionToken(),

  // Listen to events
  onEvent: (event) => {
    if (event.type === 'connect') {
      void saveConnectionId(event.payload);
    }
  },
});

In your backend, associate this connectionId to your end user.

api.post('/connection', (req, res) => {
  await User.update({
    connectionId: req.body.connectionId,
    integrationId: req.body.providerConfigKey,
  });

  res.status(200).send({
    success: true
  });
});

​

Listen for webhooks

Your backend is notified by Nango when an authorization attempt is completed, successful or not.

To set this up:

1. go to the Environment Settings tab
2. specify a Webhook URL to which Nango will send notifications
3. listen for webhooks in your backend at the specified route
4. enable the “Send New Connection Creation Webhooks” checkbox

Nango webhooks are post requests with the following JSON body:

{
    "type": "auth",
    "connectionId": "<CONNECTION-ID>",
    "authMode": "OAUTH1|OAUTH2|OAUTH2_CC|BASIC|API_KEY|APP_STORE|CUSTOM|APP|NONE|TBA",
    "providerConfigKey": "<INTEGRATION-ID>",
    "provider": "<API-CONFIGURATION-ID>",
    "environment": "dev" | "prod",
    "success": true | false,
    "operation": "creation" | "override" | "unknown",
    "error": "<ERROR>"
}

For each successful authorization attempt, persist the connection ID & integration ID in your database. You will need them to retrieve the connection credentials later.

​

You are ready

Your users can now launch Nango Connect and connect to any of your integrations, Nango is taking care of the rest.