v3 Authentication changes
The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.
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 API 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
In v3 we've taken the opportunity to clarify some of the language we use to refer to the 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 old name), the documentation and Nylas UIs are being updated to use the clearer language.
- The integration object you created in your Nylas application to store provider details is now called a connector.
- Native authentication is now called Custom authentication.
- The provider integration applications for example your GCP project or Azure application, are now called provider auth applications .
- Service accounts, also sometimes called app permissions, are now called Bulk authentication grants to better reflect their use.
- The
redirect_uriset in Nylas applications using hosted authentication is now called thecallback_urito help distinguish it from the Nylasredirect_uriset in provider auth application.
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).
The API v3 Beta adds more 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, API v3 also formalizes bulk authentication Grants (formerly known as "Service Accounts"). A bulk authentication Grant is a special kind of account used by an application or cloud provider compute workload rather than a person. Applications can use bulk authentication accounts 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 API v3. They now follow the [service].[region].nylas.com schema:
api.nylas.com→api.us.nylas.comcanada.api.nylas.com→api.us.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 API v3, the concept of "grants" (as in "the user granted you this access") replaces the concept of "connected accounts". This name better reflects Nylas' new offering and lays the groundwork for future enhancements and features.
The Nylas v3 APIs return a grant_id instead of an account_id in their responses to reflect this change. The new path format for Email, Calendar, and Contacts 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/messagesfor OAuth refresh/access token when you have a per-Grant token./v3/grants/[grant-id]/messagesfor API Key usage which can be used with any Grant ID.
Re-authentication and webhook notifications
In API v3, the authentication and re-authentication processes do not produce historical webhooks (webhook notifications for events that happened before the auth completed)
This means that when a grant expires or is otherwise invalidated in v3, re-authenticating does not produce webhook notifications for events that occurred while the grant was out of service.
To find and backfill events that occurred while a grant was invalid, find the timestamps on the grant.expired and grant.updated webhooks that correspond to the grant in question. You might want to log or otherwise save these notifications when you receive them so you can query and analyze them later.
As soon as the user re-authenticates, you can use the Nylas APIs to directly query the provider for changes that happened during that time. You do not need to wait for any synchronization status to complete.
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.