Google APIs use the OAuth 2.0 protocol for user permissions and consent. If your application accesses Google user data with Google APIs, you might have to take additional steps to comply with Google’s OAuth 2.0 policies and complete the verification process before you publish your application.
Gmail scopes that read or modify mail are restricted, and restricted scopes trigger OAuth verification plus a Cloud App Security Assessment (CASA) for any app that handles the data on its servers. The Calendar and Contacts scopes that Nylas uses are sensitive and need verification only.
Which Gmail scopes are restricted?
Section titled “Which Gmail scopes are restricted?”Google classifies 8 Gmail API scopes as restricted: gmail.readonly, gmail.compose, gmail.insert, gmail.modify, gmail.metadata, gmail.settings.basic, gmail.settings.sharing, and the full-access https://mail.google.com/ scope. Any app that requests one of them needs restricted scope verification, and an app that stores or transmits that data on a server also needs a security assessment.
The table lists each restricted scope with Google’s own description from the Gmail API scopes reference.
| Restricted scope | Google’s description |
|---|---|
https://www.googleapis.com/auth/gmail.readonly | View your email messages and settings. |
https://www.googleapis.com/auth/gmail.compose | Manage drafts and send emails. |
https://www.googleapis.com/auth/gmail.insert | Add emails into your Gmail mailbox. |
https://www.googleapis.com/auth/gmail.modify | Read, compose, and send emails from your Gmail account. This scope does not allow immediate, permanent deletion of threads and messages, bypassing the trash. |
https://www.googleapis.com/auth/gmail.metadata | View your email message metadata such as labels and headers, but not the email body. |
https://www.googleapis.com/auth/gmail.settings.basic | See, edit, create, or change your email settings and filters in Gmail. |
https://www.googleapis.com/auth/gmail.settings.sharing | Manage your sensitive mail settings, including who can manage your mail. |
https://mail.google.com/ | Read, compose, send, and permanently delete all your email from Gmail. |
Two other Gmail scopes in the Nylas scope set aren’t restricted: gmail.send is sensitive and gmail.labels is non-sensitive, so neither one triggers the security assessment. The set also includes 3 of the restricted scopes (gmail.readonly, gmail.modify, and gmail.compose), as the Google scopes table shows. Apps for personal use with fewer than 100 users skip verification, along with the other exceptions. To pick the smallest scope set for your use case, see the Gmail API OAuth scopes reference.
Sign in with Google branding guidelines
Section titled “Sign in with Google branding guidelines”To complete the brand verification process, your application must have the “Sign in with Google” button that meets Google’s branding guidelines. This applies to the OAuth flow for both personal Gmail (@gmail.com) and Workspace email addresses.
For Hosted authentication, Nylas recommends you do one of the following:
- Configure the OAuth login prompt by setting the
promptparameter withselect_providerordetect,select_provider. For more information, see Configuring the OAuth login prompt.- If you add a
login_hintthat’s a personal Gmail or Workspace email address and you don’t configure apromptduring the Hosted auth flow, the user is immediately directed to the Google OAuth screen, without clicking the “Sign in with Google” button. This can result in delays or failure in verification.
- If you add a
- Use the pre-approved “Sign in with Google” button with the “Connect your account” button or other provider login buttons in your application. For more information, see Google’s official Sign in with Google branding guidelines.
For Bring Your Own Authentication, use the pre-approved “Sign in with Google” button with the “Connect your account” button or other provider login buttons in your application.
Google OAuth verification
Section titled “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. |
- If your app requests one or more sensitive scopes and doesn’t meet any of the criteria for an exception, you need to complete a Google verification process.
- If your app requests one or more restricted scopes and doesn’t meet any of the criteria for an exception, you need to complete both Google verification and security assessment processes. For the security assessment process, Google assigns your app an assurance level and provides instructions for completing the assessment.
For more information, see Google’s OAuth API verification FAQs.
CASA security assessment
Section titled “CASA security assessment”Google runs the restricted scope security assessment through the App Defense Alliance’s Cloud App Security Assessment (CASA) framework. According to Google’s security assessment help page, CASA assigns each app to the AL1 or AL2 assurance level based on user count, requested scopes, and other signals, and “all applications must be revalidated every year.” Google’s restricted scope verification policy sets the deadline at least every 12 months after your assessor’s Letter of Assessment (LOA) approval date.
Google scopes
Section titled “Google scopes”The following are the Google scopes that Nylas projects use:
| Scope type | Scope | Description | Verification | Security assessment |
|---|---|---|---|---|
| Sensitive | gmail.send | Send messages only. No read or modify privileges on mailbox. | ☑️ | — |
| Sensitive | calendar | See, edit, share, and permanently delete all calendars you can access using Google Calendar. | ☑️ | — |
| Sensitive | calendar.readonly | See and download any calendar you can access using Google Calendar. | ☑️ | — |
| Sensitive | calendar.events | See and edit events on all your calendars. | ☑️ | — |
| Sensitive | calendar.events.readonly | See events on all your calendars. | ☑️ | — |
| Sensitive | contacts | See, edit, download, and permanently delete your contacts. | ☑️ | — |
| Sensitive | contacts.readonly | See and download your contacts. | ☑️ | — |
| Sensitive | contacts.other.readonly | See and download contacts that are saved in your “Other Contacts”. | ☑️ | — |
| Sensitive | directory.readonly | See and download your organization’s Google Workspace directory. | ☑️ | — |
| Restricted | gmail.readonly | Read all resources and their metadata. No write operations. | ☑️ | ☑️ |
| Restricted | gmail.modify | All read/write operations except immediate, permanent deletion of threads and messages, bypassing Trash. | ☑️ | ☑️ |
| Restricted | gmail.compose | Create, read, update, and delete drafts. Send messages and drafts. | ☑️ | ☑️ |
Nylas projects also use the gmail.labels scope, which is neither sensitive or restricted and requires no Google verification or security assessment. The gmail.labels scope allows apps to create, read, update, and delete labels.
Exceptions to verification and security assessment
Section titled “Exceptions to verification and security assessment”- Apps for personal use with fewer than 100 users
- Apps that are set to “Testing” and not “In production”
- Apps that are configured to work only with internal Google accounts within your organization
- Apps that have been allowed by Google Workspace admins
For the full list, see Google’s when is verification not needed help page.
How do you skip Google verification with Nylas?
Section titled “How do you skip Google verification with Nylas?”The Nylas Google Shared App, part of the Accelerator add-on for the annual Pro plan, lets your users authenticate through a Google Cloud project that has already passed OAuth verification and CASA. It covers every Google scope the API supports, including restricted Gmail scopes, and Nylas handles the reassessment Google requires every 12 months.
Pro Annual customers add the Accelerator add-on through self-service on the Billing page in the Nylas Dashboard. On the Enterprise plan, the Google Shared App is a separate add-on: contact the Nylas Sales team. Once it’s on your plan, you turn it on with the Nylas Google OAuth Credentials toggle on a Google connector in the Dashboard, and you can go live with Google authentication the same day. Your API calls don’t change. The tradeoffs are worth weighing before you switch:
| Your own Google Cloud project | Nylas Google Shared App | |
|---|---|---|
| Verification and CASA | You complete both, then revalidate every 12 months | Already completed; Nylas handles renewals |
| Consent screen name | Your app’s name | ”Nylas” |
| Custom Hosted Authentication hostname | Supported | Not supported |
| Scope selection | You choose in the connector | You choose in the connector |
| Availability | No add-on required | Annual Pro plan with the Accelerator add-on, or an Enterprise add-on |
Users who already authenticated through your own project need to re-authenticate after the switch, and they get new grant IDs. Using the Nylas Google Shared App covers setup and gradual migration. If you keep your own project, requesting only gmail.send, gmail.labels, and the Calendar and Contacts scopes keeps you out of the security assessment, and the Gmail API OAuth scopes reference helps you pick the smallest set.
Google OAuth verification guide
Section titled “Google OAuth verification guide”The Google verification and security assessment processes can be daunting, but our Google OAuth verification guide can help you understand what needs to be done and provide step-by-step instructions on how to do it.