Pick the wrong OAuth scopes and you pay for it twice. Request gmail.modify when you only read mail, and Google pushes you into a third-party security assessment that can cost five figures and add weeks of review before you launch. Request too little and the API returns 403 Forbidden on the first write. This page gives the exact scope strings per provider so you request the narrowest set that still works.
For the OAuth flow itself, how each provider approves scopes, and token refresh, see Connect user accounts with OAuth. This reference goes one level deeper into the provider scope strings that page summarizes.
Google OAuth scopes
Section titled “Google OAuth scopes”Google scopes are full URIs prefixed with https://www.googleapis.com/auth/, and Google sorts them into 3 tiers: non-sensitive, sensitive, and restricted. The restricted tier, which includes gmail.modify and gmail.readonly, triggers OAuth verification plus an annual security assessment before production. The table below maps each of the 8 common tasks to the scope Nylas requests.
| Task | Scope | Tier |
|---|---|---|
| Read email messages | https://www.googleapis.com/auth/gmail.readonly | Restricted |
| Send email | https://www.googleapis.com/auth/gmail.send | Sensitive |
| Modify or delete messages | https://www.googleapis.com/auth/gmail.modify | Restricted |
| Manage folders (labels) | https://www.googleapis.com/auth/gmail.labels | Restricted |
| Read and write calendars | https://www.googleapis.com/auth/calendar | Sensitive |
| Read and write events | https://www.googleapis.com/auth/calendar.events | Sensitive |
| Read contacts | https://www.googleapis.com/auth/contacts.readonly | Sensitive |
| Read and write contacts | https://www.googleapis.com/auth/contacts | Sensitive |
Restricted scopes are the ones that force a security assessment, so confirm you need write access before you add them. The Google security assessment guide covers the verification timeline and what the assessment reviews.
Microsoft OAuth scopes
Section titled “Microsoft OAuth scopes”Microsoft uses short Graph permission names like Mail.Read, with no URI prefix. There are two flavors: delegated permissions, which act on behalf of the signed-in user, and application permissions, which act tenant-wide and always need admin consent. Nylas uses delegated permissions, and a tenant admin can still require consent for any of the 7 scopes below before users connect.
| Task | Graph scope |
|---|---|
| Read email messages | Mail.Read |
| Send email | Mail.Send |
| Modify or delete messages | Mail.ReadWrite |
| Read and write calendars | Calendars.ReadWrite |
| Read contacts | Contacts.Read |
| Keep a refresh token | offline_access |
| Read the signed-in user | User.Read |
Always include offline_access, or the access token expires after about 60 to 90 minutes with no way to refresh it. Some organizations lock down their Microsoft 365 tenant so that any scope needs admin approval first. The Microsoft admin approval guide walks through granting tenant-wide consent.
Choose the least-privilege scope set
Section titled “Choose the least-privilege scope set”Request the smallest scope that covers your features, then add scopes only when a feature needs them. This keeps Google off the security-assessment track where possible and shortens the consent screen users approve. The mapping below covers 3 common app types and the minimal scopes each one needs across the 2 providers.
| App type | Google scopes | Microsoft scopes |
|---|---|---|
| Read-only inbox | gmail.readonly | Mail.Read, offline_access |
| Send-only | gmail.send | Mail.Send, offline_access |
| Full calendar | calendar, calendar.events | Calendars.ReadWrite, offline_access |
The principle is least privilege: every extra scope widens the data a leaked token can reach and adds friction at consent time. A read-only mailbox client that requests gmail.modify takes on the restricted-scope assessment for write access it never uses. Drop scopes you don’t call.
Things to know about scopes
Section titled “Things to know about scopes”You set scopes on the Nylas connector, not per API call, and the hosted OAuth flow at GET /v3/connect/auth requests exactly that set. A few details change how and when those scopes take effect, and getting them wrong is the most common reason a working integration starts returning 403.
- Changing scopes can force re-authentication. Add a scope after a user already connected and their existing grant doesn’t gain it. Google and Microsoft only grant new scopes at consent time, so the user has to re-authenticate through the flow again to pick up the wider access.
- Incremental authorization. Both providers let you request scopes in stages instead of all at once. Ask for read access on day one, then request send access the first time a user clicks “send”. Smaller initial consent screens convert better.
- Google verification takes weeks. Sensitive and restricted scopes require OAuth verification, and the restricted tier adds an annual third-party security assessment on top. Plan for several weeks of lead time before launch, not days.
- Microsoft admin consent is one click but blocking. A tenant admin grants consent once for the whole organization, after which every user connects without their own prompt. Until that click happens, users in a locked-down tenant can’t connect at all.
The canonical scope lists live with each provider: the Google OAuth 2.0 scopes reference and the Microsoft Graph permissions reference. Cross-check any scope against these before you add it, because providers rename and deprecate scopes over time.
What’s next
Section titled “What’s next”- Connect user accounts with OAuth for the full hosted flow and token refresh
- Build a custom OAuth connector for bringing your own Google or Microsoft credentials
- Authentication overview for the grant model and every auth method
- Google provider guides for GCP setup and verification