Authentication scopes
As you work with Nylas, you'll need to use authentication scopes to control the level of access Nylas has to your end users' data. This page explains those scopes and how to use them.
📝 Nylas scopes are no longer used in v3. Instead, 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 end users, on a per-provider basis. Each provider has its own set of scopes, and your end users either approve or reject them when they authenticate with your Nylas application.
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:
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 Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
GET |
|
|
|
POST |
|
|
|
POST |
|
|
|
GET |
|
|
|
POST |
|
|
|
GET |
|
|
| Automatic conferencing creation |
Microsoft Teams: | |
Calendar and Events notification scopes
| Notification trigger | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
|
|
|
|
|
|
|
For more information about Calendar and Events notifications, see the Calendar and Events notification schemas.
Email API scopes
| Endpoint | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
GET |
|
|
|
PUT |
|
|
|
GET |
|
|
|
POST |
|
|
|
POST |
|
|
|
PUT |
|
|
|
POST |
|
|
|
POST |
|
|
|
GET |
|
|
|
POST |
|
|
|
GET |
|
|
|
GET |
No scopes are required because scheduled email messages are stored with Nylas. To send scheduled email messages, you need | |
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 Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For more information about Email notifications, see the Messages, Message tracking, and Folder notification schemas.
Order Consolidation API scopes
| Endpoint | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
GET |
|
|
ExtractAI webhook scopes
| Endpoint | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
|
|
|
Contacts API scopes
| Endpoint | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
GET |
|
|
|
POST |
|
|
|
Note: To access contacts with the | ||
Contacts notification scopes
| Notification trigger | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
|
|
|
For more information about Contact notifications, see the Contact notification schemas.
Scheduler API scopes
| Endpoint | Google Scopeshttps://www.googleapis.com/auth/... | Microsoft Scopeshttps://graph.microsoft.com/... |
|
POST |
|
|
|
GET |
|
|
|
POST |
|
|
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.