Summary
[!note] 📚 Pilotflow Series: Building a Gmail Addon
- The $50,000 Lie That Almost Killed My Gmail Addon — June 8
- Gmail OAuth Scope Tiers Decoded ← you are here
- Pre-Development Codebase Analysis — June 22
- Legal Documents for Gmail Addons — June 29
In the previous post, I wrote about how the CASA certification myth nearly killed Pilotflow before I wrote a single line of code. The short version: the $50,000 number circulating in developer forums describes the most expensive assessment option, not the standard one. And more importantly, the right scope design often sidesteps the restriction entirely.
But how do you know which scope to use? That requires understanding Google’s three-tier classification — a system that most addon documentation glosses over, leaving developers to piece it together from error messages during OAuth verification.
This post is the clear explanation I wish I’d found on page one.
Three Tiers, Three Different Conversations
When your Google Workspace addon requests OAuth scopes, Google classifies them into one of three tiers. The tier doesn’t just determine what data your app can access — it determines the conversation Google has with your user during authorization.
Tier 1: Public scopes
→ Standard OAuth consent screen
→ No additional verification required
→ Blue shield icon in consent dialog
Tier 2: Sensitive scopes
→ OAuth verification required (free, 4–6 weeks)
→ Yellow/orange warning in consent dialog
→ Users must explicitly accept extended access
Tier 3: Restricted scopes
→ CASA Tier 2 certification required ($540–$75,000+)
→ Red warning in consent dialog
→ Enterprise admins can block installation
The consent screen difference matters more than most developers expect. A user who sees a red warning during installation has a fundamentally different first impression of your addon than one who sees a blue shield. Before choosing a scope, it’s worth asking: what does this scope look like to my user?
Takeaway: Scope tier affects security requirements AND user trust signals during installation. The consent screen color is the user’s first impression of your security posture.
The Gmail Scope Table
Here’s the classification for the Gmail scopes most addon developers encounter:
| Scope | Tier | Access | Certification |
|---|---|---|---|
gmail.addons.current.message.readonly |
Sensitive | Currently open message only | OAuth verification (free) |
gmail.addons.current.message.action |
Sensitive | Action on current message | OAuth verification (free) |
calendar.addons.current.event.read |
Public | Current calendar event | None |
gmail.readonly |
Restricted | Entire inbox (read) | CASA + OAuth |
gmail.modify |
Restricted | Entire inbox (read + modify) | CASA + OAuth |
gmail.send |
Restricted | Send as user | CASA + OAuth |
The pattern is clear: scopes that operate on the current context (what the user is actively looking at) are sensitive or public. Scopes that operate on the entire mailbox in the background are restricted.
This distinction reflects a real difference in risk. An addon that can read the email currently open is under user supervision — the user chose to open that email, sees the addon running in the sidebar, and can close both. An addon with full inbox read access can exfiltrate email history silently, in the background, without any user action triggering it.
Pilotflow’s Scope Decision
For Pilotflow, the core user workflow is: open an email thread → see insights in the sidebar → decide what to do. That workflow fits gmail.addons.current.message.readonly exactly.
What it doesn’t fit is background batch processing — reading through the last six months of emails while the user is doing something else. That’s not what Pilotflow needs to do for the user; it’s what I initially imagined having, because more access felt like more capability.
Separating “access I imagined having” from “access the user workflow actually requires” is one of the most valuable scope design exercises. The question to ask is: what is the user doing at the moment my addon runs? If the user is reading an email, the current-message scope is sufficient. If the user needs to trigger a background action, you can ask for that specific permission at the time of the trigger — not in advance.
[!note] The “just in case” trap Requesting broad scopes “just in case” you might need them later is the most common mistake in OAuth scope design. Unused permissions are a trust liability, not a safety net. Request what you need now; expand later if a specific user workflow genuinely requires it.
The Testing Status Strategy
One practical challenge during development: restricted-scope APIs may behave differently in testing than in production, because your app isn’t certified yet. Google provides a “Testing” status that lets you test with restricted scopes using a limited set of approved test accounts (up to 100 users).
For Pilotflow, I used this approach:
- During development: Use the addon with a test Gmail account added to the approved list
- Before MVP launch: Complete OAuth verification for the sensitive scopes in use
- After launch: Monitor whether any restricted-scope features get requested by actual users before investing in CASA assessment
The Testing Status strategy means you can build and validate the product with real email data before committing to any certification path. If users never request the restricted-scope feature, you never pay for the certification.
What Happens If You Get It Wrong
I’ve seen two failure modes:
Requesting restricted scopes before certification. Your app will fail the Workspace Marketplace submission review. Google’s review team checks scope classifications against certification status. If you request gmail.readonly without CASA certification, the submission is rejected — not flagged, rejected.
Requesting sensitive scopes without OAuth verification. Your app enters a warning-heavy consent flow. Users see “This app hasn’t been verified by Google” with an option to go back. Some users proceed. Many do not. The drop-off rate on unverified consent screens is significant — I’ve seen estimates of 30–50% abandonment. For a B2B tool targeting enterprise users, unverified status can also trigger admin-level blocks across the entire organization.
[!info] The verification timeline to plan for OAuth verification takes 4–6 weeks. CASA assessment takes 4–12 weeks depending on the TAP and assessment type. Build this timeline into your launch planning — not as an afterthought after the code is done.
Applying This to Your Own Addon
When designing scopes for a Gmail Workspace addon, work through these questions in order:
- What is the user doing when your addon runs? If it’s reading a specific email, start with current-message scopes.
- Does your feature require background access? If yes, is that requirement technical or architectural? Can the design be adjusted?
- For each scope you’re considering: Look it up in Google’s OAuth 2.0 Scopes for Google APIs documentation. Find its classification.
- Calculate the certification cost and timeline for any restricted scopes. Include this in your MVP cost.
- Ask: can the same user outcome be achieved with a less invasive scope? Often the answer is yes — and the less invasive scope also delivers a better user experience at the consent screen.
The next post covers pre-development codebase analysis — specifically, what I found when I analyzed the existing codebase before writing a line of new code, including a concurrency bug that would have caused silent data loss.
