← library
Security assessment
Email / Google Workspace·curated + hand-verified·checked 2026-10-28

Gmail (Google)

mail.google.com ↗
difficulty
5/5

Working in an hour for up to 100 test users. Reading mail in production needs restricted-scope verification plus an annual third-party security assessment (CASA). Plan for weeks and start early.

First working connection
~1 hour (Testing mode, ≤100 users, 7-day refresh tokens)
Production / approved
Send-only: ~1 week · Read/modify mail: several weeks + yearly CASA
Composio managed OAuth
Available: ship today
Composio offers a managed Gmail app. That's the fastest way to ship while your own verification runs, but users will see Composio's app on the consent screen.
who does itagent 2you 6provider 0
evidencetested 2sourced 31inferred 4

01Pick your path

Internal (Workspace only)
when Every user is in your own Google Workspace org.
→ No verification, no 100-user cap. Only your org's users can connect.
Testing mode
when Prototype, demo, design partners.
→ Up to 100 users, 'unverified app' warning, refresh tokens expire after 7 days.
Production: sensitive scopes only (e.g. gmail.send)
when Your agent only sends mail.
→ Brand + sensitive-scope verification. Google says it typically takes 3–5 business days.
Production: restricted scopes (gmail.readonly, gmail.modify, …)
when Your agent reads, triages or drafts mail. This is most AI-agent use cases.
→ Restricted-scope verification plus a CASA security assessment, repeated every 12 months.

02Time & effort

Hands-on work
~2 workdays – ~7 workdays
Waiting on others
2 weeks – 12 weeks
You're actually working
3% of elapsed time
Phases
7
start↑ first working connection, then production pathproduction
  1. DEVCreate Cloud project, consent screen, OAuth client30–60 minutesinferred
  2. PRODVerify domain in Search Console, publish privacy policy + homepage2–8 hourssourced[g-brand][g-branding-help]
  3. PRODBrand verificationwait 2–3 dayssourced[g-brand]Automated check runs in minutes. Google says 2–3 business days overall.
  4. PRODScope justification + demo video3–8 hourssourced[g-sensitive]
  5. PRODScope review (sensitive: 3–5 business days; restricted: several weeks)wait 1–6 weekssourced[g-sensitive][g-restricted]
  6. PRODCASA self-scan + fix findings (restricted scopes only)1–5 daysinferred[casa-t2]Run the scan per the ADA guide and remediate. Effort depends on findings.
  7. PRODAssessor validation → Letter of Validationwait 1–6 weeksinferred[casa-t2][nylas]A third-party assessor, not Google. Nylas reported about 2 weeks with SOC 2 already in hand.
agent can do it you waiting on providerbar widths ∝ √time, so short tasks stay visible

03Steps

0/8 done

Get a working connection

  1. Pick the narrowest Gmail scope. It decides your entire timeline.agentsourced[gmail-scopes]

    gmail.labels is non-sensitive. gmail.send is sensitive. gmail.readonly, gmail.modify, gmail.compose, gmail.metadata and mail.google.com/ are RESTRICTED and trigger CASA. An agent can audit your code for requested scopes and propose the minimum.

  2. Create separate Cloud projects for testing and productionyousourced[g-exempt][g-brand]

    Google's policy expects separate projects. Submit only the production project for verification.

    ↗ console.cloud.google.com/projectcreate
  3. Configure branding, audience and an OAuth client (Web application)yousourced[g-branding-help]

    In Google Auth Platform: Branding (app name, support email, logo), Audience (External + Testing; add test users), Clients (Web app, redirect URIs). Add authorized domains BEFORE adding redirect, homepage or privacy URLs.

    ↗ console.developers.google.com/auth/branding
  4. Ship to ≤100 test users while verification runsyousourced[g-oauth][g-exempt]

    In Testing mode users see an 'unverified app' screen and refresh tokens expire after 7 days (unless you only request name/email/profile). Build re-auth into the agent so it doesn't silently die every week.

Make it production-ready

  1. Verify domain ownership and publish homepage + privacy policyyousourced[g-brand][g-restricted]

    Verify the top private domain in Google Search Console with a project Owner/Editor account. The homepage must be public, describe the app and link the privacy policy on the same domain. The policy must disclose Google user data handling and Limited Use.

    ↗ search.google.com/search-console/about
  2. Draft scope justifications and a demo-video shot listagentsourced[g-sensitive]

    For each scope, explain the feature and why a narrower scope isn't enough. The video must show the full OAuth flow and how each scope is used. An agent can draft both from your code and product description.

    ◆ prepared by agent · Scope justification template
    Scope: https://www.googleapis.com/auth/gmail.readonly
Feature: <Agent name> summarizes the user's unread email each morning and drafts replies the user approves.
Why this scope: We must read message bodies to summarize them. gmail.metadata exposes headers only, and gmail.labels exposes no content.
Data handling: Message content is processed in memory, not stored beyond <N> days, never used to train models, and never shared with third parties. This complies with the Google API Services User Data Policy, including Limited Use.
Video: 0:00 sign-in + consent screen (shows app name + scope) → 0:40 summary feature using the scope → 1:30 data deletion control.
  3. Submit in the Verification Center and watch both contact inboxesyousourced[g-sensitive]

    Trust & Safety follows up by email to the developer contact and support emails. Missed emails stall the review.

    ↗ console.developers.google.com/auth/verification
  4. Complete CASA (restricted scopes only)yousourced[casa-t2][g-restricted]

    Google emails you when you're in scope. Tier 2: scan your app per the ADA guide, send results to an authorized assessor, receive a Letter of Validation. Existing certifications may speed this up. Repeat every 12 months.

    ↗ appdefensealliance.dev/casa/tier-2/tier2-overview

04Requirements, scopes & nuances

You'll need

  • ▸A domain you own, verified in Google Search Console, hosting the homepage and privacy policy. sourced[g-brand][g-branding-help]
  • ▸Privacy policy that discloses how Google user data is accessed, used, stored and shared, and complies with the Limited Use requirements. sourced[g-restricted]
  • ▸A demo video showing the OAuth flow and scope usage (sensitive and restricted reviews). sourced[g-sensitive]
  • ▸Restricted scopes accessed through your servers: annual CASA assessment by a Google-approved assessor. sourced[g-restricted]
  • ▸Assessment fees may apply and vary by assessor. We could not find an authoritative current price. inferred

Gotchas

  • !gmail.metadata sounds harmless but is restricted. Some third-party guides wrongly list gmail.readonly as merely sensitive. sourced[gmail-scopes]
  • !Testing mode issues 7-day refresh tokens, so agents silently lose access weekly. sourced[g-oauth]
  • !Adding a new restricted scope later can trigger re-verification and reassessment. Get scope choices right first. sourced[g-restricted]
  • !Workspace admins can block unverified or sensitive-scope apps for their org even after you're verified, so enterprise users may need admin allow-listing. sourced[g-sensitive]
  • !The privacy policy must be on the same domain as the homepage. A Notion page or Google Doc won't pass. sourced[g-restricted][g-branding-help]
Scope / permissionTierNoteEvidence
openid email profilebasicIdentity only. Testing-mode refresh tokens don't expire after 7 days for these.sourced[g-oauth]
gmail.labelsbasicNon-sensitive: see and edit labels.sourced[gmail-scopes]
gmail.sendsensitiveSend on the user's behalf. Sensitive review, no CASA.sourced[gmail-scopes]
gmail.readonlyrestrictedRead messages. Restricted, needs CASA.sourced[gmail-scopes]
gmail.metadatarestrictedHeaders/labels only, but still restricted.sourced[gmail-scopes]
gmail.modify / gmail.composerestrictedRead+write / drafts. Restricted.sourced[gmail-scopes]
https://mail.google.com/restrictedFull access incl. permanent delete. Google says request only if you truly need immediate deletion.sourced[gmail-scopes]

05If you get blocked

✕Verification is taking weeks and you need to launch.sourced[composio][g-exempt]

→ Launch on Composio's managed Gmail app, or Internal mode for your own org, while your own app is reviewed. Keep Testing mode for ≤100 design partners.

✕Brand verification failed automatically.sourced[g-brand][g-branding-help]

→ Usually domain or branding mismatch: unverified authorized domain, privacy policy on another domain, or a name resembling a Google product. Fix it and re-run, or request manual review.

✕Reviewer asks you to justify a scope.sourced[g-sensitive]

→ Reply in the Verification Center with the feature, the exact scope, and why narrower scopes fail. Downgrade to a narrower scope if you can't justify it.

06Evidence: what was tested, sourced, and still uncertain

$ probes: live GETs with a dummy client_id, no credentials
✓ OIDC discovery document → 200
https://accounts.google.com/.well-known/openid-configuration
authorization_endpoint = https://accounts.google.com/o/oauth2/v2/auth
∴ Standard OIDC, so any OAuth library works and endpoints are confirmed.
✓ Authorize endpoint with a fake client_id → 302
https://accounts.google.com/o/oauth2/v2/auth?client_id=probe_invalid&response_type=code&scope=openid
Redirect to /signin/oauth/error, authError decodes to 'invalid_client: The OAuth client was not found.'
∴ Google validates the client before login. A typo in client_id fails immediately and clearly.

Sources read

  1. [gmail-scopes] Google — Choose Gmail API scopes official
  2. [g-restricted] Google — Restricted scope verification official
  3. [g-sensitive] Google — Sensitive scope verification official
  4. [g-brand] Google — Brand verification official
  5. [g-branding-help] Google Cloud Help — Manage OAuth app branding official
  6. [g-exempt] Google Cloud Help — When is verification not needed official
  7. [g-oauth] Google — Using OAuth 2.0 to access Google APIs official
  8. [casa-t2] App Defense Alliance — CASA Tier 2 process official
  9. [nylas] Nylas — Google OAuth verification: costs, timelines third-party
  10. [composio] Composio — Managed OAuth apps directory official
  11. [probe] Live HTTP probes run by the agent (dummy client_id, no credentials) probe

Still uncertain

  • ? Google does not publish an SLA for restricted-scope review ('can take several weeks'). Our 1–6 week range is an estimate.
  • ? CASA tier assignment, assessor fees and duration vary. We did not run an assessment.
  • ? We did not submit an app for verification. Steps reflect current docs (console UI labels change often).