Skip to main content

​
Who is impacted

If you use the Nango public key in your frontend, you are impacted by this migration. To check if you are using the public key, inspect your frontend code where the Nango object is instantiated. If the config parameter includes publicKey, you are affected. If it uses connectSessionToken, you are already up-to-date.

​
Changes summary

  1. The Nango public key is replaced with a short-lived Connect session token, fetched from your backend and passed to your frontend
  2. The connection ID is now randomly generated by Nango instead of being specified manually
  3. The connection ID is returned via backend webhooks instead of the frontend SDK

​
Migration timeline

Public keys and HMAC signatures will be supported until July 31, 2025 (six months from the announcement on January 31, 2025).

​
Why this deprecation?

For security reasons. If you were using the HMAC signature (strongly recommended in the docs), your authorization flow was already secure. However, not all users implemented HMAC, and we want to enforce best-in-class security practices by default. For those not using HMAC, the risk of attack was minimal but theoretically possible. We have no reports of such attacks, but feel free to reach out for more details.

​
Improvements with the Connect session

  1. The new Connect session flow is secure by default and replaces the HMAC signature. Randomly generated connection IDs further enhance security
  2. Connection IDs are now unique across integrations, which will allow us to simplify API endpoints by transitioning from composite keys (connection ID + integration ID) to a single unique connection ID
  3. The Connect session will let us provide additional API capabilities that can be called directly and securely from the frontend
  4. The Connect session unlocks our pre-built authorization UI, which simplifies collecting API keys, basic credentials, and OAuth flows with custom parameters. This UI also validates end-user inputs and provides guidance on required credentials
The Connect session works with both the pre-built authorization UI and custom authorization UIs. Custom authorization UIs are not being deprecated; they remain a critical feature and fully supported.The deprecated public key, however, was only compatible with custom authorization UIs and did not support the pre-built authorization UI.

​
Migration steps

This migration is split into 3 steps. You can migrate at your own pace, but we recommend doing it in this order. During the migration, both connect session and public key authentication will work so you don’t have to do all 3 steps at once.
Existing connections will keep the custom id you have used until now but new connections will have a random id. Your code will need to support both.

​
Step 1: Attach a user to all existing connections

Attach a user to all existing connections. This step will allow you to use connect sessions with existing connections. This will also be used to attribute webhooks to the correct end user.
  • Node
  • cURL
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: process.env['<NANGO-SECRET-KEY>'] });
await nango.patchConnection({
  connectionId: '<CONNECTION-ID>',
  provider_config_key: '<INTEGRATION-ID>',
}, {
  end_user: {
      id: '<USER-ID>',
      [...]
  }
});
Check endpoint documentation here.

​
Step 2: Implement the Connect and reconnect flows

Follow the steps in this guide, focusing on these key changes: Connect session token is now required to be passed to the frontend SDK. This improves security and allows you to pass additional information to the connection.

​
Step 3: Clean up

Finally, remove all usage of the public key and HMAC from your frontend.
Questions, problems, feedback? Please reach out in the Slack community.