Version:
Only show these results:

Authentication scopes in Nylas v2

Nylas supports granular authentication scopes to improve security for your end users. You can limit the permissions and data that Nylas requests during authentication using the scopes parameter. To do this, use either the /oauth/authorize endpoint for Hosted authentication, or the /connect/authorize endpoint for Native authentication.

If a request doesn't have the required scopes to perform an action, your application must re-authenticate the account so the end-user can accept the correct permissions.

ℹ️ Authentication scopes is available for Entry, Core, and Plus plans.

Nylas scopes

These scopes are required to make API requests through Nylas. These are requested as part of both Native authentication and Hosted authentication.

Nylas Scope Description
email Send and modify all messages, threads, file attachments, and read email metadata like headers
email.modify Read and modify all messages, threads, file attachments, folders (MS) and labels (Google), and read email metadata like headers. Does not include send.
email.read_only Read all messages, threads, file attachments, drafts, and email metadata like headers. No write operations.
email.send Send messages only. No read or modify privileges on users' emails. Using email.send as the only scope with Gmail accounts may lead to unexpected threading behavior. Accounts using this as the only scope will also always be in an initializing state.
email.folders_and_labels Read and modify folders or labels, depending on the account type.
email.metadata Read email metadata including headers and labels/folders, but not the message body or file attachments.
email.drafts Read and modify drafts. Does not include send.
calendar Read and modify calendars and events.
calendar.free_busy Exchange WebSync (EWS) accounts should add this scope to access the /free-busy endpoint.
calendar.read_only Read calendars and events.
room_resources.read_only Read available room resources for an account. Room resources for Office 365 is an admin consent required permission.
contacts Read and modify contacts.
contacts.read_only Read contacts.

Default Scopes

If scopes aren't provided during authentication, Nylas uses the following default scopes:

  • email
  • contacts
  • calendar

Metadata

Office365, Exchange, and other Microsoft accounts don't offer a scope equivalent to the Nylas email.metadata scope. This means that if your app requests email.metadata, Nylas requests a more permissive scope to cover those needs, and then restricts access within the Nylas system.

In this case, Nylas usually requests an email.read_only scope instead of email.metadata. This grants Nylas the resulting access, but Nylas restricts the requesting app so it doesn't have permission to access the email body.

Microsoft scopes

These scopes are required when creating an Azure app to connect to a Microsoft provider:

Microsoft Scope App Manifest Description
User.Read Microsoft Graph Sign in and read user profile.
offline_access Microsoft Graph Maintain access to data you have given it access to.
openid Microsoft Graph Sign users in.
profile Microsoft Graph View users' basic profile.
User.Read Microsoft Graph Sign in and read user profile.
EAS.AccessAsUser.All Office 365 Exchange Online Access mailboxes via Exchange ActiveSync (EAS).
EWS.AccessAsUser.All Office 365 Exchange Online Access mailboxes via Exchange Web Services (EWS).
Calendars.Read.Shared Microsoft Graph Nylas supports Microsoft Graph for events only.
Calendars.ReadWrite.Shared Microsoft Graph Nylas supports Microsoft Graph for events only.

Gmail scopes

These scopes are required when creating a app in the Google console:

Google Scope Nylas Scopes
userinfo.email Required Google scopes
userinfo.profile Required Google scopes
openid Required Google scopes
gmail.compose email.drafts, email.send
gmail.modify email.modify, email.send
gmail.labels email.folders_and_labels
gmail.metadata email.metadata
gmail.send email.send
gmail.readonly email.read_only. Includes gmail.metadata.
calendar calendar
calendar.readonly calendar.read_only
contacts contacts
admin.directory.resource.calendar.readonly room_resources.read_only

Inconsistency for Google Accounts

Due to a known bug with the Google API, you shouldn't authenticate Google accounts with the email.metadata scope if you also intend to use more permissive scopes such as email.read_only or email.modify. gmail.readonly includes gmail.metadata.

In most cases, you don't need to combine the more permissive scopes to include the less permissive ones. Combining metadata with those scopes causes Google to return 403 errors, and the account in question won't sync properly.

Service accounts - calendar data only

Nylas is currently able to onboard Google Workspaces and Exchange-based accounts for calendar data only.

Authenticating accounts

When authenticating an account using Hosted authentication or Native authentication, only request the scopes you need. For example, if you authenticate with only the calendar scope, then you will get a 403 response.

403 response example

{
  "message": "You do not have access to the required scopes. You provided a token which has the following scopes: ['email.read_only', 'email.send']. You would need a token with at least one of the following scopes: ['email.modify']",
  "type": "api_error"
}

IMAP

You can only use the calendar or contact scopes without the email scope if you are working with Google and Exchange accounts. IMAP accounts don't have actual calendars and contacts, but instead Nylas parses iCalendar files and email participants to populate events and contacts. These are included in the email scope.

More resources