Using granular scopes to request user data

As you work with Nylas, you’ll need to use scopes to control the level of access Nylas has to your users’ data.

What are scopes?

Granular 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 Creating grants with IMAP authentication.

Default and supported scopes

A scope reaches a grant only after clearing three layers, and each layer is configured in a different place. The provider app sets the ceiling, the connector sets what hosted auth requests by default, and an individual auth request can narrow or widen that default for one grant.

Layer	Where you set it	What it controls
Provider app	Google Cloud OAuth consent screen, or the Azure app registration’s API permissions	Every scope the provider will ever approve for your app. Google verification is judged against this list, and Microsoft admin consent covers these permissions.
Connector default scopes	The connector’s Authenticate scopes in the Dashboard, or the scope array on the Connectors API	What hosted auth requests when the auth request doesn’t specify scopes.
Per-grant scopes	The scope parameter on GET /v3/connect/auth, or the scopes on a custom auth request	Overrides the connector defaults for that grant only.

Nylas adds the identity scopes below to every auth request, so the provider app must have them enabled even though your connector and auth requests never need to name them. Nylas adds nothing else. If the auth request omits scope and the connector has no default scopes, the grant gets identity access only. Request every mail, calendar, and contacts scope in the tables on this page at the connector or per-grant layer.

Provider	Identity scopes Nylas always requests
Google	openid, https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile
Microsoft	User.Read, offline_access, openid, email

Two checks apply to any scope you request through Nylas:

• It must be enabled on the provider app. Nylas forwards it, but the provider evaluates the request against your app’s configured permissions. A scope that isn’t enabled there fails at the provider’s consent or verification step.
• It must be in the tables on this page. The API accepts only these scopes. Google scopes must match the full scope string exactly as listed, such as https://www.googleapis.com/auth/gmail.send, so a short name like gmail.send on its own is rejected. Microsoft scopes work as the short name (Mail.Read) or the prefixed form (https://graph.microsoft.com/Mail.Read).

A scope outside the supported list is never forwarded to the provider. Creating a connector, creating a grant, or starting hosted auth for a single provider with an unsupported scope returns 400 with the error code common.scope_not_allowed. The multi-provider hosted flow, where the user picks a provider on the login page, drops unsupported scopes silently instead.

Nylas API scopes

Each of the Nylas APIs requires different scopes to function properly. The tables in the following sections list the scopes you need to work with specific Nylas features.

All scopes must include the fully-qualified URI path for the provider. The tables shorten the full scope URIs for space reasons, so be sure to add the provider prefix when requesting scopes.

Messages API scopes

Google

All scopes except https://mail.google.com/ must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/messages GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>	/gmail.readonly	/gmail.modify
PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>	/gmail.modify	—
DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>	/gmail.modify	https://mail.google.com/ (hard-delete)
POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose	/gmail.readonly	/gmail.modify
PUT /v3/grants/<NYLAS_GRANT_ID>/messages/clean	/gmail.readonly	—
POST /v3/grants/<NYLAS_GRANT_ID>/messages/send	/gmail.send	/gmail.compose /gmail.modify

You need to request the /gmail.send scope if you want to schedule messages to be sent in the future. For more information, see Schedule messages to send in the future.

Microsoft

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/messages GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>	Mail.Read	Mail.ReadWrite Mail.Read.Shared Mail.ReadWrite.Shared
PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>	Mail.ReadWrite	Mail.ReadWrite.Shared
POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose	Mail.Read	Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared
PUT /v3/grants/<NYLAS_GRANT_ID>/messages/clean	Mail.Read	—
POST /v3/grants/<NYLAS_GRANT_ID>/messages/send	Mail.ReadWrite Mail.Send	Mail.ReadWrite.Shared

You need to request the Mail.ReadWrite and Mail.Send scopes if you want to schedule messages to be sent in the future. For more information, see Schedule messages to send in the future.

Yahoo

Endpoint	Scopes
GET /v3/grants/<NYLAS_GRANT_ID>/messages GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>	email mail-r
PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose POST /v3/grants/<NYLAS_GRANT_ID>/messages/send	email mail-r mail-w

Drafts API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/drafts GET /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	/gmail.readonly	/gmail.compose
POST /v3/grants/<NYLAS_GRANT_ID>/drafts PUT /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	/gmail.compose	—
POST /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	/gmail.compose	/gmail.modify

Microsoft

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/drafts GET /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	Mail.Read	Mail.ReadWrite Mail.Read.Shared Mail.ReadWrite.Shared
POST /v3/grants/<NYLAS_GRANT_ID>/drafts PUT /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	Mail.ReadWrite	Mail.ReadWrite.Shared
POST /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	Mail.ReadWrite Mail.Send	Mail.ReadWrite.Shared

Yahoo

Endpoint	Scopes
GET /v3/grants/<NYLAS_GRANT_ID>/drafts GET /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	email mail-r
POST /v3/grants/<NYLAS_GRANT_ID>/drafts/ PUT /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID> POST /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>	email mail-r mail-w

Folders API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/folders GET /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID> POST /v3/grants/<NYLAS_GRANT_ID>/folders PUT /v3/grants/NYLAS_GRANT_ID>/folders/<FOLDER_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>	/gmail.labels	/gmail.modify

Microsoft

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/folders GET /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>	Mail.Read	Mail.ReadWrite Mail.Read.Shared Mail.ReadWrite.Shared
POST /v3/grants/<NYLAS_GRANT_ID>/folders PUT /v3/grants/NYLAS_GRANT_ID>/folders/<FOLDER_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>	Mail.ReadWrite	Mail.ReadWrite.Shared

Yahoo

Endpoint	Scopes
GET /v3/grants/<NYLAS_GRANT_ID>/folders GET /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>	email mail-r
POST /v3/grants/<NYLAS_GRANT_ID>/folders/ PUT /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>	email mail-r mail-w

Attachments API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>	/gmail.readonly	/gmail.modify

Microsoft

All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>	Mail.Read	Mail.ReadWrite Mail.Read.Shared Mail.ReadWrite.Shared

Yahoo

Endpoint	Scopes
GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>	email mail-r

Contacts API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/contacts GET /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> GET /v3/grants/<NYLAS_GRANT_ID>/contacts/groups	/contacts.readonly /contacts.other.readonly /directory.readonly	—
POST /v3/grants/<NYLAS_GRANT_ID>/contacts PUT /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>	/contacts	—

You must request the /contacts.other.readonly scope to access contacts from the inbox source, and /directory.readonly for contacts from the domain source.

Microsoft

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/contacts GET /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> GET /v3/grants/<NYLAS_GRANT_ID>/contacts/groups	Contacts.Read People.Read	—
POST /v3/grants/<NYLAS_GRANT_ID>/contacts PUT /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>	Contacts.ReadWrite	—

You must request the People.Read scope to access contacts from the inbox and domain sources.

iCloud

iCloud does not use OAuth scopes. Authenticate a native iCloud grant with an app-specific password to use CardDAV Contact read and write endpoints. A generic hosted IMAP grant does not provide native iCloud CardDAV access.

Yahoo

Native Yahoo CardDAV Contacts use the bearer credential established by the Yahoo connector and grant. There is no separate Contacts scope to request. A generic Hosted IMAP grant does not provide native Yahoo CardDAV access.

Calendar API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/calendars GET /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID> POST /v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy	/calendar.readonly	/calendar
POST /v3/grants/<NYLAS_GRANT_ID>/calendars PUT /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>	/calendar	—
POST /v3/calendars/availability	/calendar.readonly	/calendar

You need to request the /calendar scope if you want to use the primary keyword to reference the primary calendar associated with a grant. For more information about the primary keyword, see Find a calendar ID.

Microsoft

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/calendars GET /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID> POST /v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy	Calendars.Read	Calendars.ReadWrite
POST /v3/grants/<NYLAS_GRANT_ID>/calendars PUT /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>	Calendars.ReadWrite	—
POST /v3/calendars/availability	Calendars.Read	Calendars.ReadWrite

Events API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/events GET /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>	/calendar.events.readonly	/calendar.events /calendar /calendar.readonly
POST /v3/grants/<NYLAS_GRANT_ID>/events PUT /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID> POST /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp	/calendar.events	/calendar
GET /v3/grants/<NYLAS_GRANT_ID>/resources	/admin.directory.resource. calendar.readonly	—

You need to request the /calendar scope if you want to use the primary keyword to reference the primary calendar associated with a grant. For more information about the primary keyword, see Find a calendar ID.

Microsoft

Endpoint	Required scopes	Other scopes
GET /v3/grants/<NYLAS_GRANT_ID>/events GET /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>	Calendars.Read	Calendars.ReadWrite
POST /v3/grants/<NYLAS_GRANT_ID>/events PUT /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID> POST /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp	Calendars.ReadWrite	—
GET /v3/grants/<NYLAS_GRANT_ID>/resources	Place.Read.All	—

You need to request the OnlineMeetings.ReadWrite scope if you want to automatically create conferencing details on events. For more information, see Enable autocreate for conferencing.

Zoom

You need to request the meeting:write:meeting, meeting:update:meeting, meeting:delete:meeting, and user:read:user scopes if you want to automatically create conferencing details on events. For more information, see Enable autocreate for conferencing.

Scheduler API scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations PUT /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIG_ID> GET /v3/grants/<NYLAS_GRANT_ID>/scheduling/availability	/calendar.readonly	/calendar
POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings PATCH /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID>	/calendar.events	/calendar

Microsoft

Endpoint	Required scopes	Other scopes
POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations PUT /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIG_ID> GET /v3/grants/<NYLAS_GRANT_ID>/scheduling/availability	Calendars.Read	Calendars.ReadWrite
POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings PATCH /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID>	Calendars.ReadWrite	—

Nylas notification scopes

Each of Nylas’ notification triggers requires different scopes to function properly. The tables in the following sections list the scopes you need to work with specific Nylas features.

All scopes must include the fully-qualified URI path for the provider. The tables shorten the full scope URIs for space reasons, so be sure to add the provider prefix when requesting scopes.

Messages notification scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
message.send_success message.send_failed	/gmail.send	—
message.created message.updated	/gmail.metadata	gmail.readonly /gmail.modify
message.bounce_detected	/gmail.readonly /gmail.send	/gmail.modify

If your account uses the /gmail.metadata scope, Nylas sends message.*.metadata notifications with limited information. For more information, see Using webhooks with Nylas.

Microsoft

Notification trigger	Required scopes	Other scopes
message.send_success message.send_failed	Mail.ReadWrite Mail.Send	—
message.created message.updated	Mail.Read	Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared
message.bounce_detected	Mail.Read Mail.Send	Mail.ReadWrite

Yahoo

All message.* notifications require the email and mail-r scopes.

Threads notification scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
thread.replied	/gmail.readonly /gmail.send	/gmail.modify

Microsoft

Notification trigger	Required scopes	Other scopes
thread.replied	Mail.Read Mail.Send	Mail.ReadWrite

Yahoo

All thread.* notifications require the email and mail-r scopes.

Folders notification scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
folder.created folder.updated folder.deleted	/gmail.metadata	/gmail.readonly gmail.modify

If your account uses the /gmail.metadata scope, Nylas sends message.*.metadata notifications with limited information. For more information, see Using webhooks with Nylas.

Microsoft

Notification trigger	Required scopes	Other scopes
folder.created folder.updated folder.deleted	Mail.Read	Mail.ReadWrite Mail.ReadWrite.Shared Mail.Read.Shared

Yahoo

All folder.* notifications require the email and mail-r scopes.

Contacts notification scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
contact.updated contact.deleted	/contact.readonly /contacts	—

Microsoft

Notification trigger	Required scopes	Other scopes
contact.updated contact.deleted	Contacts.Read	Contacts.Read.Shared Contacts.ReadWrite Contacts.ReadWrite.Shared

iCloud

Native iCloud grants can emit contact.updated and contact.deleted without a separate OAuth scope. The grant must use the iCloud connector and a valid app-specific password.

Yahoo

Native Yahoo grants do not emit contact.updated or contact.deleted, including for Contacts API writes.

Calendar notification scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
calendar.created calendar.updated calendar.deleted	/calendar.events.readonly	/calendar.events

Microsoft

Notification trigger	Required scopes	Other scopes
calendar.created calendar.updated calendar.deleted	Calendars.Read	Calendars.Read.Shared Calendars.ReadWrite Calendars.ReadWrite.Shared

Events notification scopes

Google

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
event.created event.updated event.deleted	/calendar.events.readonly /calendar.readonly	/calendar.events

Microsoft

Notification trigger	Required scopes	Other scopes
event.created event.updated event.deleted	Calendars.Read	Calendars.Read.Shared Calendars.ReadWrite Calendars.ReadWrite.Shared

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. The processes that you need to complete depends on whether your application requests sensitive 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 our Google verification and security assessment guide.