Pre-requisite: complete the Configuration guide.

Authorization overview.

​
1. Generate a session token (backend)

In your backend, set up an API endpoint that your frontend will call before each authorization attempt to retrieve a session token from Nango.

Here’s an example of how your backend can retrieve a session token from Nango (API / Node SDK references):

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: '<END-USER-ID>',
      email: '<OPTIONAL-END-USER-EMAIL>',
      display_name: '<OPTIONAL-END-USER-DISPLAY-NAME>',
    },
    organization: {
      id: '<OPTIONAL-ORG-ID>',
      display_name: '<OPTIONAL-ORG-DISPLAY-NAME>'
    },
    allowed_integrations: ['<INTEGRATION-ID>'],
  });

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

Passing a list of integration IDs in allowed_integrations will display a list of integrations that the end user can pick from:

Nango's default authorization UI.

Passing a single integration ID in allowed_integrations will send the end user directly to this integration’s authorization flow:

Nango's default authorization UI.

​
2. Trigger the auth flow (frontend)

In your frontend, load the Nango frontend SDK, retrieve the session token from the backend, and trigger the authorization flow.

​
Option 1: Use the default UI (Nango Connect)

Nango’s default authorization UI comes with pre-built features:

  • Displays the necessary input fields, validates their format & provides end-user instructions
  • Authorizes a specific integration or can display a list of integrations to choose from
  • Is fully whitelabel, without any Nango branding

Nango's default authorization UI.

import Nango from '@nangohq/frontend';

const nango = new Nango();
const connect = nango.openConnectUI({
  onEvent: (event) => {
    if (event.type === 'close') {
      // Handle modal closed.
    } else if (event.type === 'connect') {
      // Handle auth flow successful.
    }
  },
});

const res = await fetch('/sessionToken', { method: 'POST' }); // Retrieve the session token from your backend.
connect.setSessionToken(res.sessionToken); // A loading indicator is shown until this is set.

(SDK reference)

​
Option 2: Use your custom UI

Refer to the Authorize in your app (custom UI) guide.

​
3. Listen for webhooks & save the Connection ID (backend)

The connection ID, a UUID generated by Nango, is required to manage the connection and access its credentials & data. So you need to persist this ID.

Upon successful authorization, Nango will send a webhook to your backend with the connection ID.

To set up this webhook:

  1. go to the Environment Settings tab in the Nango UI
  2. specify a Webhook URL where Nango should send notifications
  3. enable the Send New Connection Creation Webhooks option
  4. create the specified route in your backend to handle Nango webhooks

Successful authorization webhooks sent by Nango are POST requests with the following JSON body:

{
    "type": "auth",
    "operation": "creation",
    "success": true,
    "connectionId": "<CONNECTION-ID>",
    "endUser": { "endUserId": "<END-USER-ID>", "organizationId": "<ORGANIZATION-ID>" },
    ...
}

For each successful authorization, persist the connectionId value alongside its corresponding user or organization, designated by endUser.endUserId and endUser.organizationId.

​
4. Run the authorization flow

You can now test the authorization flow directly from your app and verify that a connection is created in the Nango UI Connections tab.

​
Troubleshoot authorization errors

If an authorization request fails, you can analyze the relevant log in the Logs tab of the Nango UI.

​
Re-authorize an existing connection

Details in this guide.

​
Next

You have successfully set up the authorization flow for your users. Next steps:

  • View new connections & associated credentials in the Connections tab of the Nango UI
  • Retrieve connection credentials with the API or Node SDK
  • Sync data from APIs
  • Perform actions with APIs
  • Perform direct request to APIs

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