​

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

• Node
• cURL

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
  });
});

​

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)

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 roken 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 webhoooks & 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.

​

Reconnect an existing connection

When testing or troubleshooting an issue, you may need a user to re-authorize an API. Nango allows you to do this without deleting and recreating the connection. Instead, you can reconnect an existing connection while preserving its metadata and configuration.

In your backend, use the POST /connect/sessions/reconnect endpoint (API/SDK reference) to generate a session token specifically for reconnecting a user. This token is then used on the frontend in the same way as when creating a connection, but it will reconnect the existing connection instead.

• Node
• cURL

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 to reconnect
  const res = await nango.createReconnectSession({
    connection_id: "<CONNECTION-ID>",
    integration_id: '<INTEGRATION-ID>',
  });

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

​

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