Authentication scopes

As you work with Nylas, you’ll need to use authentication scopes to control the level of access Nylas has to your users’ data. This page explains those scopes and how to use them.

Nylas scopes are no longer used in v3. Instead, you specify the scopes for each provider. You can use the Detect Provider endpoint to help determine which scopes to send with an authentication request. For more information about the changes to authentication in v3, see the New in v3 docs.

What are scopes?

Authentication scopes represent sets of permissions you request from your users, on a per-provider basis. Each provider has its own set of scopes, and your users either approve or reject them when they authenticate with your Nylas application.

IMAP connectors don’t support scopes. For more information, see Create grants with IMAP authentication.

You set the scopes that you want to request when you create your provider auth app and any connectors. For more information, see the following documentation:

• Create a Google auth app
• Create an Azure auth app
• Create a connector

You can also overwrite the default scopes associated with a connector on a per-request basis. To do this, make a GET /v3/connect/auth request and include the scope string.

Nylas v3 scopes

Each of the Nylas APIs and notification sets requires different scopes to function. The tables in the following sections list the Google and Microsoft scopes you need to work with specific Nylas features.

All scopes must include the fully qualified URI path for the provider. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you’re already using one of the permissive scopes, you don’t need to add the more restrictive scope.

Calendar and Events API scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
GET /calendars GET /calendars/<CALENDAR_ID> POST /calendars/free-busy	/calendar.readonly ☑️ /calendar	Calendars.Read ☑️ Calendars.ReadWrite
POST /calendars PUT /calendars/<CALENDAR_ID> DELETE /calendars/<CALENDAR_ID>	/calendar ☑️	Calendars.ReadWrite ☑️
POST /calendars/availability	/calendar.readonly ☑️ /calendar	Calendars.Read ☑️ Calendars.ReadWrite
GET /events GET /events/<EVENT_ID>	/calendar.events.readonly ☑️ /calendar.events /calendar (Required to use primary keyword when referencing calendars.)	Calendars.Read ☑️ Calendars.ReadWrite
POST /events PUT /events/<EVENT_ID> DELETE /events/<EVENT_ID> POST /events/<EVENT_ID>/send-rsvp	/calendar.events ☑️ /calendar (Required to use primary keyword when referencing calendars.)	Calendars.ReadWrite ☑️
GET /v3/grants/<NYLAS_GRANT_ID>/resources	/admin.directory.resource.calendar.readonly ☑️️	Place.Read.All ☑️️
Automatic conferencing creation	Microsoft Teams: OnlineMeetings.ReadWrite. Google Meet: No extra scopes required. Conferencing is part of the Event object. Zoom: meeting:write:meeting and user:read:user.

Calendar and Events notification scopes

Notification trigger	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
calendar.created calendar.updated calendar.deleted	/calendar.events.readonly ☑️ /calendar.events	Calendars.Read ☑️ Calendars.Read.Shared Calendars.ReadWrite Calendars.ReadWrite.Shared
event.created event.updated event.deleted	/calendar.events.readonly ☑️ /calendar.events	Calendars.Read ☑️ Calendars.Read.Shared Calendars.ReadWrite Calendars.ReadWrite.Shared

For more information about Calendar and Events notifications, see the Calendar and Events notification schemas.

Email API scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
GET /messages GET /messages/<MESSAGE_ID>	/gmail.readonly ☑️ /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.Read.Shared Mail.ReadWrite.Shared
PUT /messages/<MESSAGE_ID> DELETE /messages/<MESSAGE_ID>	/gmail.modify ☑️	Mail.ReadWrite ☑️ Mail.ReadWrite.Shared
GET /drafts GET /drafts/<DRAFT_ID>	/gmail.readonly ☑️ /gmail.compose	Mail.Read ☑️ Mail.ReadWrite Mail.Read.Shared Mail.ReadWrite.Shared
POST /drafts PUT /drafts/<DRAFT_ID> DELETE /drafts/<DRAFT_ID>	/gmail.compose ☑️	Mail.ReadWrite ☑️ Mail.ReadWrite.Shared
POST /messages/smart-compose POST /messages/<MESSAGE_ID>/smart-compose	/gmail.readonly ☑️ /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared
PUT /messages/clean	/gmail.readonly ☑️	Mail.Read ☑️
POST /messages/send POST /events/<EVENT_ID>/send-rsvp	/gmail.send ☑️ /gmail.compose /gmail.modify	Mail.ReadWrite and Mail.Send ☑️ Mail.ReadWrite.Shared and Mail.Send
POST /messages/send (using draft)	/gmail.compose ☑️ /gmail.modify	Mail.ReadWrite and Mail.Send ☑️ Mail.ReadWrite.Shared and Mail.Send
GET /folders GET /folders/<FOLDER_ID>	/gmail.labels ☑️ /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared
POST /folders PUT /folders/<FOLDER_ID> DELETE /folders/<FOLDER_ID>	/gmail.labels ☑️ /gmail.modify	Mail.ReadWrite ☑️ Mail.ReadWrite.Shared
GET /attachments/<ATTACHMENT_ID>	/gmail.readonly ☑️ /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared
GET /messages/schedules GET /messages/schedules/<SCHEDULE_ID> DELETE /messages/schedules/<SCHEDULE_ID>	No scopes are required because scheduled email messages are stored with Nylas. To send scheduled email messages, you need gmail.send for Google, or Mail.ReadWrite and Mail.Send for Microsoft.

Email scopes for Yahoo OAuth

If you use Yahoo OAuth to connect to your end users’ email inboxes, you must include the following scopes in your Yahoo provider auth app.

📝 Note: All Email notifications require the Yahoo email and mail-r scopes.

Endpoint	Yahoo scopes
GET /messages GET /messages/<MESSAGE_ID> GET /drafts GET /drafts/<DRAFT_ID> GET /folders GET /folders/<FOLDER_ID> GET /attachments/<ATTACHMENT_ID>	email mail-r
PUT /messages/<MESSAGE_ID> DELETE /messages/<MESSAGE_ID> POST /drafts PUT /drafts/<DRAFT_ID> DELETE /drafts/<DRAFT_ID> POST /messages/smart-compose POST /messages/<MESSAGE_ID>/smart-compose POST /messages/send POST /messages/send (using draft) POST /folders PUT /folders/<FOLDER_ID> DELETE /folders/<FOLDER_ID>	email mail-r mail-w

Email notification scopes

Notification trigger	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
message.send_success message.send_failed	/gmail.send ☑️	Mail.ReadWrite and Mail.Send ☑️
message.created message.updated	/gmail.readonly ☑️ /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared
message.bounce_detected	/gmail.readonly and /gmail.send ☑️ /gmail.modify	Mail.Read and Mail.Send ☑️ Mail.ReadWrite and Mail.Send
thread.replied	/gmail.readonly and /gmail.send ☑️ /gmail.modify	Mail.Read and Mail.Send ☑️ Mail.ReadWrite and Mail.Send
folder.created folder.updated folder.deleted	/gmail.readonly ☑️ or /gmail.labels with refactor /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared

For more information about Email notifications, see the Messages, Message tracking, and Folder notification schemas.

Order Consolidation API scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-order GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-shipment GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-return	/gmail.readonly ☑️	Mail.Read ☑️ Mail.Read.Shared

ExtractAI webhook scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
message.intelligence.order message.intelligence.tracking message.intelligence.return	/gmail.readonly ☑️	Mail.Read ☑️ Mail.Read.Shared

Contacts API scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
GET /contacts GET /contacts/<CONTACT_ID> GET /contact_groups	/contacts.readonly, /contacts.other.readonly, and /directory.readonly * ☑️	Contacts.Read and People.Read * ☑️
POST /contacts PUT /contacts/<CONTACT_ID> DELETE /contacts/<CONTACT_ID>	/contacts ☑️	Contacts.ReadWrite ☑️
Note: To access contacts with the inbox source, you must use the contacts.other.readonly scope for Google, and the People.Read scope for Microsoft. For contacts with the domain source, you must use the directory.readonly Google scope, and the People.Read Microsoft scope.

Contacts notification scopes

Notification trigger	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
contact.updated contact.deleted	/contact.readonly ☑️ /contacts ☑️	Contacts.Read ☑️ Contacts.Read.Shared Contacts.ReadWrite Contacts.ReadWrite.Shared

For more information about Contact notifications, see the Contact notification schemas.

Scheduler API scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
POST /scheduling/configurations PUT /scheduling/configuration/<SCHEDULER_CONFIG_ID>	/calendar.readonly ☑️ /calendar	Calendars.Read ☑️ Calendars.ReadWrite
GET /scheduling/availability	/calendar.readonly ☑️ /calendar	Calendars.Read ☑️ Calendars.ReadWrite
POST /scheduling/bookings DELETE /scheduling/bookings/<BOOKING_ID> PATCH /scheduling/bookings/<BOOKING_ID>	/calendar.events ☑️ /calendar	Calendars.ReadWrite ☑️

Google OAuth verification

If your application accesses Google user data with Google APIs and requests certain scopes, you might have to complete a Google verification process, and a separate security assessment process. Which process or processes depends on whether your app requests sensitive scopes or restricted scopes.

Scope Type	Required Processes	Google Policy and Requirements
Sensitive	Google verification	Your application must follow Google’s API Services User Data Policy.
Restricted	Both Google verification and security assessment	Your application must follow Google’s API Services User Data Policy and meet additional requirements for specific scopes.

For more information, see the Google verification and security assessment guide.