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.

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 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.) /calendar.readonly	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.)	Calendars.ReadWrite ☑️
GET /resources	/admin.directory.resource.calendar.readonly ☑️️	Place.Read.All ☑️️
Automatic conferencing creation	Microsoft Teams: OnlineMeetings.ReadWrite. Google Meet: No extra scopes required. 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.readonly ☑️ /calendar.events	Calendars.Read ☑️ Calendars.Read.Shared Calendars.ReadWrite Calendars.ReadWrite.Shared

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	/gmail.send ☑️ /gmail.compose /gmail.modify	Mail.ReadWrite ☑️ Mail.Send ☑️ Mail.ReadWrite.Shared
POST /drafts/<DRAFT_ID>	/gmail.compose ☑️ /gmail.modify	Mail.ReadWrite ☑️ Mail.Send ☑️ Mail.ReadWrite.Shared
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 messages are stored with Nylas. To send scheduled 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 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 /drafts/<DRAFT_ID> 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 ☑️ 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 ☑️ /gmail.send ☑️ /gmail.modify	Mail.Read ☑️ Mail.Send ☑️ Mail.ReadWrite Mail.Send
thread.replied	/gmail.readonly ☑️ /gmail.send ☑️ /gmail.modify	Mail.Read ☑️ Mail.Send ☑️ Mail.ReadWrite Mail.Send
folder.created folder.updated folder.deleted	/gmail.readonly ☑️ /gmail.labels (with refactor) /gmail.modify	Mail.Read ☑️ Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared

Order Consolidation API scopes

Endpoint	Google Scopes https://www.googleapis.com/auth/...	Microsoft Scopes https://graph.microsoft.com/...
GET /consolidated-order GET /consolidated-shipment GET /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 ☑️ /directory.readonly ☑️	Contacts.Read ☑️ People.Read ☑️
POST /contacts PUT /contacts/<CONTACT_ID> DELETE /contacts/<CONTACT_ID>	/contacts ☑️	Contacts.ReadWrite ☑️
To access contacts with the inbox source, you need the contacts.other.readonly Google scope, and the People.Read Microsoft scope. 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

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 the Google APIs and requests certain scopes, you might have to complete the Google verification process and a separate security assessment process. Which process or processes you need to complete depends on whether your application 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	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.