​

Generate a session token (backend)

In your backend, set up an API endpoint that your frontend will call. This endpoint should request a session token from Nango and return it to the frontend.

Here’s an example of how to generate a session token using Nango’s API (API ref / Node SDK ref):

• cURL
• Node

curl --request POST \
  --url https://api.nango.dev/connect/sessions \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "end_user": {
      "id": "<END-USER-ID>",
      "email": "<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>"
    ]
  }'

​

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 Nango Connect 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 roken from your backend.
connect.setSessionToken(res.sessionToken); // A loading indicator is shown until this is set.

​

Option 2: Use your custom UI

Refer to the Authorize an API from your app with custom UI guide for details on implementing a custom user interface.

​

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.

​

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.

• cURL
• Node

curl --request POST \
  --url https://api.nango.dev/connect/sessions/reconnect \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "connection_id": "<CONNECTION-ID>",
    "integration_id": "<INTEGRATION-ID>"
  }'

const nango = new Nango({ connectSessionToken });
await nango.auth('<INTEGRATION-ID>');

​

You are ready

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
• Read data from the API
• Write data to the API
• Proxy request to the API