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

Embed the auth flow (frontend)

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

Nango's default authorization UI.

You can override the Nango default UI (docs).

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.

(Frontend SDK reference)

3

Listen for webhooks (backend)

Upon successful authorization, Nango will send a webhook to your backend with the connection ID. This connection ID, a UUID generated by Nango, is required to manage the connection and access its credentials & data. So you need to persist it in your database.

To process Nango webhooks:

  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.

Congrats 🎉 You can now run the authorization flow directly from your app and verify that a connection is created in the Connections tab.

Troubleshoot errors in the Logs tab.

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