Version:
Only show these results:

Upgrade authentication from v2.x to v3

The first step for every project migrating from Nylas v2.x to v3 is to assess and upgrade your authentication systems. When you have your auth systems working in v3, you can then test and upgrade your other code and systems.

This page explains how to upgrade a Nylas project to use v3 authentication.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

Before you begin

Before you begin to upgrade your authentication systems, you should familiarize yourself with the terminology changes in Nylas v3, and check for compatibility.

Terminology changes in v3

For Nylas v3, we've taken the opportunity to clarify some of the language we use to refer to parts of the Nylas system. While some of these changes are not yet available at the API level (meaning the API endpoints still reflect the v2 name), the documentation and Nylas UIs are being updated to use the clearer language.

  • The integration object that you create in your Nylas application to store provider details is now called a connector.
  • Provider integration applications (for example, your Google Cloud Platform project or Azure app) are now called provider auth apps.
  • Native authentication is now called Custom authentication.
  • Service accounts (sometimes called "app permissions") are now called bulk authentication grants to better reflect their use.
  • The redirect_uri set in Nylas applications that use Hosted authentication is now called the callback_uri. This helps to distinguish it from the Nylas redirect_uri set in provider auth apps.
    • The callback_uri used by webhook subscriptions is now called webhook_url to be more explicit about its use.

Check for compatibility

Before you upgrade your authentication systems, check if you're using any of the methods that are no longer supported in Nylas v3:

  • No support for unsecured HTTP: Nylas no longer supports unsecured connections over HTTP (port 80). You must now use HTTPS (port 443).
  • No support for Basic auth: Nylas no longer supports Basic authentication, and instead uses Bearer auth with either an access token or API key. If you haven't already updated your code to use Bearer auth, you must do that before you can use v3.
  • No support for Microsoft Exchange scopes with Hosted auth: Nylas v3 uses Microsoft Graph scopes only. If your v2 project uses Exchange scopes, you must translate them into Graph scopes. You can use the Graph scopes directly because v3 no longer uses Nylas scopes.
  • No support for server-side hosted auth: Nylas v3 no longer supports server-side hosted authentication. You must use the new Hosted OAuth method.

If you're using any of these methods, you must update them or migrate to a more modern version before you proceed.

Create provider auth applications for v3

The steps to create and configure provider auth apps should be pretty familiar in Nylas v3, but some things have changed. You must update your provider auth apps to be compatible with v3.

Nylas recommends that you create new provider auth apps to test your v3 upgrades before moving on to upgrade your production provider auth apps. This prevents any permission mismatch issues that might arise from affecting your production provider auth apps' verification status.

For all applications, the Authorized redirect URIs have changed:

  • For U.S. Hosted authentication use https://api.us.nylas.com/v3/connect/callback.
  • For E.U. Hosted authentication use https://api.eu.nylas.com/v3/connect/callback.

Changes to Microsoft auth applications in v3

Nylas v3 brings the following changes for Microsoft auth apps:

  • Nylas now supports Account in any organizational directory and personal Microsoft accounts. This allows for end users to authenticate using their personal accounts.
  • EWS- and EAS-related scopes have been removed, and Nylas v3 uses Microsoft Graph scopes only. See the Calculating scopes section for more information. (If you are using EWS and EAS with an on-premises Nylas deployment, contact Nylas Support for more information.)
  • Nylas no longer supports Exchange on-premises service accounts.

For complete and detailed information, see Create an Azure app for Nylas v3.

Changes to Google auth applications in v3

Nylas v3 brings the following changes for Google auth apps:

  • Nylas scopes have been removed. v3 uses Google API scopes instead. See the Calculating scopes section for more information.
  • If you're using the Nylas Email APIs with Google, you must also set up a Google Pub/Sub subscription to receive webhook notifications.

For complete and detailed information, see Create a Google authentication application for Nylas v3.

Calculating scopes

In v3, Nylas no longer uses "Nylas scopes", and directly uses the scopes from the provider instead. Nylas recommends you make a list of the API endpoints you use in your v2 project, then reference the v3 scopes documentation to compile a list of the scopes you need to add to your provider auth applications.

As you work with Nylas, you might need to update your scopes for specific APIs (for example, you might want Write permissions for your end users' email messages). You can find API-specific scope information throughout this documentation:

If you're authenticating with Microsoft, you must translate your old Exchange/EAS scopes into Microsoft Graph scopes, then add them to your Azure auth app's Entra ID system (previously "Azure ID"). For more information, see Microsoft's official Configure Azure AD Graph permissions for an app registration guide.

Create v3 Nylas applications

Nylas applications are the containers for your project's authentication configuration and general settings. They also store your end users' grants. Depending on how your project is organized, you might use separate Nylas applications to provide your end users with different experiences.

You must create applications using the v3 Nylas Dashboard. After you create an application, you can modify and interact with it using the Administration APIs. At minimum, you should create a Nylas application for testing, and a separate application for production.

⚠️ ⚠️ Keep in mind: Although you can create and manage legacy Nylas v2 applications from the v3 Dashboard, the v2 Dashboard cannot create or manage v3 applications.

Create v3 connectors

Nylas v3 requires that you create a connector for each provider that your Nylas application authenticates with (for example, Google, Microsoft, and IMAP). While this was not required for some auth methods in v2, this is required for all auth mechanisms in v3. (Yes, even you Native auth users.)

You can now set default scopes on each connector in v3. You can also pass different scopes during individual auth requests to override your defaults.

🔍 You can have only one connector for each provider per Nylas application. If you use more than one provider auth app for each provider (sometimes called "multi-tenant"), you must set up connector credentials for additional tenants.

You can now set default scopes on each connector in v3. You can also pass different scopes during individual auth requests to override your defaults.

Create IMAP connectors

Because the IMAP protocol doesn't have the concept of "scopes", you can create an IMAP connector by setting only provider_type: "imap". You do not need to include scopes or any other details.

In Nylas v3, you start the IMAP authentication process using the Bearer auth request header with your Nylas application's API key, along with the end user's IMAP username, password, and IMAP host and port.

Create Google connectors

To create a Google connector, you make a Create connector request that includes your Google Cloud Platform (GCP) client_id and client_secret, and a default set of scopes for your project. Be sure that the scopes on the connector match exactly, or are a literal subset of the scopes that your GCP app uses.

When you start an authentication request with Google, you use the Bearer auth request header with your Nylas application's API key, set provider_type: "google", and include any non-default scopes and states. If you're using Custom auth, you must also pass the end user's refresh key.

Create Microsoft connectors

⚠️ Before you create a Microsoft connector, make sure you've migrated your project's old scopes to the new Microsoft Graph scopes and entered them in your Azure application's Entra ID. Because the upgrade to Nylas v3 includes this scope update, all Microsoft users must re-authenticate to accept the new v3 scopes.

To create a Microsoft connector, you must make a Create connector request that includes your Azure client_id and client_secret, and a list of scopes.

When you start an authentication request with Microsoft, you use the Bearer auth request header with your Nylas application's API key, set provider_type: "microsoft", and include any non-default scopes and states.

Upgrading Hosted authentication to Hosted OAuth

Nylas v3 implements a Hosted OAuth authentication system that completely replaces Hosted auth from v2. The new v3 Hosted OAuth system is OAuth 2.0-compliant using the latest technical and security industry standards, and offers multiple ways to authorize requests when you complete the authentication process. See Authentication in Nylas v3 and the Authentication reference documentation for more details.

Upgrading Native authentication to Custom authentication

If you used Native auth for your v2 Nylas application, the v3 Custom auth implementation should be very familiar. The v3 requests now go through a connector, which can supply some of the provider details. This makes your v3 Custom auth requests much simpler: you now pass the provider and request token, and can include scopes overrides and a state.

See Creating grants with Custom authentication for more details.

Bulk authentication and connector credentials in v3

Nylas v3 introduces the concept of "credentials", which are packages of information that you can use when authenticating to override the default connector settings and auth methods.

You can use connector credentials to override a provider's default connector settings, for example, if you're using more than one GCP auth app to authenticate your end users. If you use this method you create a credential for the non-default provider auth app which contains the client_id and client_secret from that auth app, and any other information needed to connect. Nylas encrypts and stores that information securely, and you can then use the credential_id in Custom auth calls to log users in with that non-default provider auth app.

Connector credentials are linked to a specific provider connector in a specific Nylas application. For example, if you have a connector credential for a second Google auth app, the credential record is attached to the Google connector in your Nylas application. You cannot use the credential_id for this second auth app when authenticating with a different Nylas application.

Credentials are also used for bulk authentication with Google's Service accounts and Microsoft's "Admin consent" system. See Bulk authentication in Nylas v3 for detailed instructions.

Testing upgraded authentication

When you have your provider auth apps and connectors working, test them out by creating a grant for each type of user authentication. You can then use these grants to test when you upgrade and of the Nylas Email, Calendar, and Contacts APIs your project uses to v3.

As you test, you might find that you need to modify your new scopes for v3. If you do, remember to change them both on your provider auth apps, and in any defaults you set on the associated connectors (and connector credentials, if applicable).

What's next?

After your authentication systems are upgraded and working, the next step is to upgrade your webhook systems. You'll want webhooks working so you can get notifications about data you create, modify, or delete using the other Nylas APIs.

After you have webhooks working, you can upgrade any of the Email, Calendar, and Contacts APIs that your project uses.