Version:
Only show these results:

Changes to authentication in Nylas v3

This page lists and explains the changes to Authentication between Nylas v2.7 and v3. You can also read Features and changes in v3 for details about other changes in Nylas API v3.

Architecture changes

Nylas v3 provides a fast query system that allows your application to retrieve data directly from service providers. This means that the object IDs Nylas returns come directly from the providers, and there is no more data sync, no more waiting for syncs to complete, and no need to monitor for deltas. This also means that Nylas no longer generates an additional "Nylas ID" for objects, and instead simplifies queries by using the providers' object IDs.

Nylas also no longer returns webhooks for historical events on grant creation (when a user connects their account).

Terminology changes

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.

Authentication changes

v3 simplifies and streamlines the supported Microsoft authentication methods.

⚠️ If you are using Microsoft service accounts in v2, you must update them to use them with the new v3 implementation. In v3, Nylas no longer accepts the Microsoft Basic authentication flow, and no longer supports or accepts Microsoft Exchange scopes (you use the more granular Microsoft Graph scopes instead).

Nylas v3 no longer supports server-side hosted authentication or Exchange on-premises service accounts.

Nylas v3 adds new authentication options:

  • Hosted OAuth with API key: This method starts by using the OAuth 2.0 Authorization Code method (response_type=code) to get user authorization and create a grant, but then uses an API key to make requests on behalf of the user.
  • Hosted OAuth with access token: This method includes both an access token that expires after one hour, and a refresh token to simplify re-authentication. This method also includes PKCE support for extra security on mobile and single-page applications (SPAs) that don't have a backend.
  • Custom authentication: Imports existing credentials or an existing refresh token, and creates a grant using it.

In addition, Nylas v3 also formalizes bulk authentication grants (formerly known as "service accounts"). A bulk auth grant is a special kind of account used by an application or cloud provider compute workload rather than a person. Applications can use bulk auth grants to make and authorize API calls instead of users. This is supported by both Google and Graph API.

API format changes

Nylas no longer allows connections over HTTP (port 80), and now allows HTTPS (port 443) only.

Nylas no longer accepts Basic authentication, and instead accepts bearer-token authentication. You can use either the access token associated with a Grant or an API key as the bearer token.

The Nylas API endpoints and production domains have changed in v3. They now follow the [service].[region].nylas.com schema:

  • api.nylas.com → api.us.nylas.com
  • canada.api.nylas.com → api.us.nylas.com
  • ireland.api.nylas.com → api.eu.nylas.com

In v3 and later, you specify the version string as part of the API URI (for example, POST /v3/webhooks). The v3 Nylas API ignores the old Nylas Version header, and the v3 Dashboard no longer includes a version selector for each application.

Changing account_id to grant_id

In Nylas v3, the concept of "grants" (as in "the end user granted you this access") replaces the concept of "connected accounts". This name better reflects the new offering and lays the groundwork for future enhancements and features.

The v3 APIs return a grant_id instead of an account_id in their responses. The new path format for Email and Calendar data also includes the grant ID, which references the specific account permissions used to retrieve the data.

All Email, Calendar, and Contacts APIs include a /v3/grants/{grant-id}/ prefix. For convenience, refer to an end user's grant using either their grant_id, their email address, or (if you are using an access token for their grant) the me construction. For example, GET /messages becomes one of the following in v3:

  • /v3/grants/me/messages for OAuth refresh/access token when you have a per-grant token.
  • /v3/grants/{grant-id}/messages for API key usage which can be used with any grant ID.

Re-authentication and webhook notifications

In v3, Nylas does not produce webhook notifications for events that happened before an end user authenticated with your application. When an end user's grant expires, Nylas stops sending webhook notifications for changes because it can no longer access the account's data.

If the grant expires then becomes valid within 72 hours, Nylas produces webhook notifications for the period that the grant was out of service. This means that your application may experience a high volume of incoming webhooks while Nylas syncs the events. The best practices guide includes suggestions for how to prepare to process a large number of incoming webhooks.

If the grant expires and becomes valid after that 72 hour period, Nylas does not send backfill notifications for events that occurred while their grant was out of service. In this case, look for the grant.expired and grant.updated notifications and query the Nylas APIs for objects that changed between those timestamps.

Scopes changes

Nylas v3 also removes the concept of Nylas Scopes. Instead, you now use the provider scopes directly as needed for your application's functionality. You also specify the full provider scopes, for example gmail.modify is now https://www.googleapis.com/auth/gmail.modify.

You can now specify default scopes on the connector object for each provider, as well as for each grant. You must specify at least one set of scopes (either connector- or grant-level) to successfully authenticate. Grant scopes take precedence over connector scopes if both are set. This allows you to set "default" scopes for any grants created by authenticating with a specific provider.

The scopes you specify must match the ones you set on your provider auth application. They can be a subset, but the strings must literally match those set on the provider auth application.

For example, if your auth application lists https://www.googleapis.com/auth/calendar and https://www.googleapis.com/auth/gmail.modify, you can request just https://www.googleapis.com/auth/gmail.modify in a grant because it matches, but you cannot request https://www.googleapis.com/auth/calendar.readonly because even though it is a more restrictive scope, it is not listed in your auth application.

Tip: You can use the /v3/providers/detect endpoint to determine which provider the end-user is working from, so you can request the correct scopes.