​
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 & 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

Follow the steps in this guide, focusing on these key changes:
  • Fetch a Connect session token from your backend, pass it to your frontend, and update Nango frontend SDK method signatures accordingly.
  • Connection credentials are now received via webhooks, not the frontend SDK. You must specify a user ID (and optionally an organization ID) when fetching the Connect session token to correctly attribute webhooks. You can also attach additional information to connections for better UI display.
  • Store all existing and future connection IDs with your customer data. Since Nango now generates connection IDs randomly, they can no longer be inferred from other identifiers.
Finally, remove all usage of the public key and HMAC from your frontend.
Questions, problems, feedback? Please reach out in the Slack community.