Authentication Scopes
Nylas supports granular authentication scopes to improve security for your end-users. You can limit the permissions and data Nylas requests during authentication by using the scopes
parameter with either the /oauth/authorize
Hosted Authentication or connect/authorize
Native Authentication endpoints.
If you do not have the required scopes, you will need to re-authenticate the account and you user will need to accept the permissions.
Nylas Scopes
These scopes are required to make API requests through Nylas. These are requested as part of Native and Hosted Authentication.
Nylas Scope | Description |
---|---|
Send and modify all messages, threads, file attachments, and read email metadata like headers | |
email.modify | Read and modify all messages, threads, file attachments, 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 | 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 are not provided during authentication, scopes will default to the following:
email
contact
calendar
Metadata
Office365, Exchange, and other Microsoft accounts do not offer a scope that mirrors our email.metadata
scope. This means that if your app requests email.metadata
, we will then request a more permissive scope to cover those needs, then restrict access within our system. This will usually result in our requesting a email.read_only
scope in place of email.metadata
. Although Nylas will have the resulting access, the requesting app will not have permissions to access the email body.
Microsoft Scopes
These scopes are required when creating a Azure app.
Microsoft Scope | App Manifest | Description |
---|---|---|
User.Read | Azure Active Directory 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 |
EWS.AccessAsUser.All | Office 365 Exchange Online | Access mailboxes via Exchange ActiveSync |
Calendar.Read.Shared | Microsoft Graph | Nylas supports Microsoft Graph for events only. |
Calendar.ReadWrite.Shared | 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 should not authenticate Google accounts with the email.metadata
scope if you also intend to use more permissive scopes like email.read_only
or email.modify
. gmail.readonly
includes gmail.metadata
.
You don't need to combine the more permissive scopes include the less permissive ones in most cases. Combining metadata
with those scopes will cause Google to return 403 errors, and the account in question will not 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 Auth or Native Auth, you request only the scopes you need. For example if you authenticate with only the calendar
scope, then you will get 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
Using calendar or contact scopes without the email scope is only relevant for Google and Exchange accounts. IMAP accounts do not have actual calendars and contacts, but we parse iCalendar files and email participants to populate events and contacts when the email
scope is included.