There are cases where you need to re-authorize a connection, e.g. credentials have expired or the scopes/permissions have changed.

The simplest way is to delete and recreate the connection, but this will reset the connection’s attached data (metadata, synced records). Most of the time when testing, this is fine.

Follow the instructions below if you need to re-authorize a connection without altering it’s attached data.

​

Handle Invalid Connections in Your UI

When rendering integration settings in your application, it’s important to check if existing connections are still valid and provide users with a clear path to fix invalid connections.

​

Detect invalid connections

Before displaying integration settings, check if the connection is still valid using the GET /connection endpoint:

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

const nango = new Nango({ secretKey: process.env['<NANGO-SECRET-KEY>'] });

// Check connection status
try {
  const connection = await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');
  // Connection is valid - display normal settings
} catch (error) {
  if (error.status >= 400 && error.status < 500) {
    // Connection is invalid - display error and reconnect button
    displayReconnectUI();
  }
}

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

const nango = new Nango({ secretKey: process.env['<NANGO-SECRET-KEY>'] });

// Check connection status
try {
  const connection = await nango.getConnection('<INTEGRATION-ID>', '<CONNECTION-ID>');
  // Connection is valid - display normal settings
} catch (error) {
  if (error.status >= 400 && error.status < 500) {
    // Connection is invalid - display error and reconnect button
    displayReconnectUI();
  }
}

curl --request GET \
  --url https://api.nango.dev/connection/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID> \
  --header 'Authorization: Bearer <NANGO-SECRET-KEY>'

​

Display reconnect UI

If the response is a 4xx error, display an error message and a “Reconnect” button in your UI. When the user clicks the “Reconnect” button, trigger the reauthorization flow using the reconnect session token as described in the next section.

The ideal user flow should be:

1. User navigates to integration settings/dashboard
2. System detects invalid connection and displays error state
3. User clicks “Reconnect” button
4. Reauthorization flow is triggered
5. Connection is restored and user returns to normal settings view

​

Re-authorize a connection from your app

You can implement the re-authorization flow in your app by having your backend call a different endpoint when the connection already exists.

Instead of generating the default endpoint to generate a session token, use the POST /connect/sessions/reconnect endpoint (API/SDK reference) to generate a session token meant for reconnection. 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.

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

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

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>"
  }'

​

Re-authorize a connection from the Nango UI

To re-connect from the UI, go to the Connections tab > click Add Test Connection > click Or use deprecated flow. Pick the relevant integration and enter the connection ID of the connection you want to re-authorize.

This flow leverage’s the headless client. Check out the reference to pass the right parameters based on the integration’s authorization type (OAuth, API key, basic auth).