# Gmail: OAuth app setup and approval
Gated · Sourced · updated 27 Oct 2026 · https://oauth-guide.akshatsethi.com/apps/gmail

> You can connect your own account and up to 100 test users the same day. The scopes most Gmail integrations need (gmail.readonly, gmail.modify, gmail.compose) are restricted, so a public launch needs Google's OAuth verification and a paid, annual third-party CASA security assessment. Expect several weeks.

- **Your hands-on work:** 3–10 days
- **Waiting on Gmail:** 2–8 weeks
- **First user can connect:** Today, in about 30–60 minutes, with your own account added as a test user
- **Why Gated:** Typical Gmail scopes are restricted, and Google requires a paid third-party CASA security assessment (assessor fees of about $500–$4,500, renewed every year) before the public can connect.
- **Using Composio?** Composio has a managed Gmail OAuth app, so you can prototype without registering your own. To have your own name on the consent screen, you have to register your own app and go through Google's verification and CASA yourself.

## Path to launch
### Build: Your account
- Who can connect: You, added as a test user on an External app in Testing status, or anyone in your Workspace org if the app is Internal.
- What users see: A Google 'hasn't verified this app' warning before consent. Grants expire after 7 days.
- Effort: 30–60 min · Wait: None
- Next: Add other Google accounts to the test-user list.
- _(Docs [3, 4])_

### Beta: Test users
- Who can connect: Up to 100 test users you list by email. Each one counts against a quota that does not reset.
- What users see: An unverified-app warning. Grants and refresh tokens expire 7 days after consent, so users have to reconnect weekly.
- Effort: 5–15 min · Wait: None
- Next: Publish to production, submit for verification, pass restricted-scope review and the CASA security assessment.
- _(Docs [4])_

### Launch: Public launch
- Who can connect: Any Google account.
- What users see: A normal consent screen with your app name and logo, listing the Gmail permissions requested.
- Effort: 3–10 days · Wait: 2–8 weeks
- _(Community [5, 6, 8, 9], medium confidence)_

## Before you start
- [ ] **Google account and Google Cloud project** (You). Any Google account can create a Cloud project. Internal apps need a Google Cloud Organization, which comes from Workspace or Cloud Identity. _(Docs [4, 7])_
- [ ] **Verified domain you own** (You). Your homepage, privacy policy and redirect domains must be authorized domains, verified in Google Search Console. _(Docs [7, 9])_
- [ ] **Public homepage and privacy policy** (You). The homepage must be public, not behind a login. The privacy policy must include the Google API Services Limited Use disclosure and explain how Gmail data is handled. _(Community [9, 7], medium confidence)_
- [ ] **Demo video** (You). An English video showing the full OAuth flow, the consent screen with the exact scopes requested, and each feature that uses each scope. _(Docs [2, 7])_
- [ ] **CASA security assessment (paid, annual)** (You). Required if you store or transmit restricted-scope data on servers. A Google-empanelled assessor does it. You pay the assessor about $500–$4,500, and the Letter of Validation must be renewed every 12 months. _(Docs [1, 5, 6])_

## Steps
1. **Create a Google Cloud project** (You, 5–10 min). Sign in to the Google Cloud console and create a project for the app. Google recommends separate projects for development and production. _(Docs [7, 8])_
   - Sign in at console.cloud.google.com
   - Create a new project and name it
   - Agent: Once you're signed in, an agent can create the project.
   - Watch out: The 100-user unverified cap applies for the project's lifetime and never resets, so keep test traffic in a separate dev project.
2. **Enable the Gmail API** (Agent, 2–5 min). In the API Library, find the Gmail API and enable it for the project. _(Docs [7])_
   - APIs & Services > Library > Gmail API > Enable
   - Agent: An agent can do this in the console.
3. **Configure the OAuth consent screen** (Agent, 10–20 min). In Google Auth Platform, set the user type to External (or Internal for your org only) and fill in branding: app name, support email, logo, homepage, privacy policy, terms, authorized domains and developer contact. _(Docs [7, 4])_
   - Choose user type: External or Internal
   - Fill in app name, user support email and developer contact email
   - Add homepage, privacy policy and terms URLs
   - Add authorized domains
   - Agent: An agent can fill in the form. You choose the support and contact emails.
   - Watch out: Use a contact inbox someone monitors. Google sends all verification messages there.
4. **Add the narrowest Gmail scopes you need** (Agent, 5–10 min). On the Data Access page, add only the scopes your live features use. gmail.send is sensitive. gmail.readonly, gmail.modify, gmail.compose, gmail.metadata and https://mail.google.com/ are restricted. _(Docs [2, 9])_
   - Data Access > Add or remove scopes
   - Pick the narrowest scope that works, for example gmail.send for send-only apps
   - Agent: An agent can add the scopes once you've decided which ones you need.
   - Watch out: Scopes on the consent screen must match what your app actually requests. A mismatch is a common reason for rejection.
5. **Create a Web application OAuth client** (Agent, 5–10 min). Create an OAuth client ID of type Web application and add your redirect URI under Authorized redirect URIs. A person should copy the client secret into your OAuth client's configuration. _(Docs [7])_
   - Clients > Create client > Web application
   - Add your redirect URI exactly as your OAuth client sends it
   - You copy the client ID and secret into your OAuth client
   - Agent: An agent can create the client and enter your redirect URI. It hands off to you before the secret is shown.
   - Watch out: Request access_type=offline and prompt=consent so you get a refresh token.
6. **Add test users and connect** (Agent, 5–15 min). While the app is in Testing status, add your account and up to 99 others under Audience > Test users, then run a test connection through your OAuth client. _(Docs [4, 9])_
   - Audience > Test users > Add users
   - Connect your own account through your OAuth client and call the Gmail API
   - Agent: An agent can add the emails and run a test connection. You sign in to Google during consent.
   - Watch out: In Testing, grants and refresh tokens expire after 7 days, and each test user permanently uses up one of the 100 slots.
7. **Verify domain ownership in Search Console** (You, 15–60 min). Verify the domains for your homepage, privacy policy and redirect URIs in Google Search Console, using an account that is an owner or editor on the project. _(Community [9], medium confidence)_
   - Add a DNS TXT record or use another Search Console verification method
   - Agent: An agent can start the Search Console flow. You make the DNS change.
   - Watch out: An unverified callback or homepage domain is a common rejection reason.
8. **Record demo video and write justifications** (You, 3–8 h). Record an English demo showing the consent screen with the exact scopes and every feature that uses each scope. For each scope, write which feature uses it and why a narrower scope won't work. _(Docs [2, 7, 9])_
   - Upload the video as unlisted on YouTube
   - Draft a justification for each scope
   - Add the Limited Use disclosure to your privacy policy
   - Agent: An agent can draft justifications. You record the video.
   - Watch out: Vague justifications and videos that don't show the real consent screen are the most common reasons for resubmission.
9. **Publish the app and submit for verification** (You, 30–60 min). Click Publish app to move to production, then use Prepare for verification in the Verification Center, add the justifications and video link, and submit. _(Docs [7])_
   - Audience > Publish app
   - Verification Center > Prepare for verification > Submit
   - Agent: An agent can fill in the forms. You submit.
   - Watch out: If you change anything after submitting, you have to resubmit the form or review stalls.
10. **Wait for Trust & Safety review** (Provider, wait 3–14 days). Google's OAuth review team emails project owners and editors, often within 24–48 hours, and may ask for changes. Approval of the use case often comes in under a week, and Google's own estimate is several weeks. _(Community [9, 8], medium confidence)_
   - Watch out: Reply within a day. Each back-and-forth adds days.
11. **Complete the CASA security assessment** (You, 2–5 days). When Google tells you to start, hire an empanelled CASA assessor (most apps are Tier 2), fix any scan findings and get a Letter of Validation. Assessor fees run about $500–$4,500. _(Docs [5, 6, 9])_
   - Choose an assessor from the App Defense Alliance list
   - Run SAST/DAST scans and answer the questionnaire
   - Fix findings and get the Letter of Validation
   - Agent: An agent can help prepare the questionnaire answers. You pay and deal with the assessor.
   - Watch out: Pick an assessor early. Tier 3 (for example, with domain-wide delegation) costs much more.
12. **Wait for CASA and final approval** (Provider, wait 2–4 weeks). Google says Tier 2 assessments take 2–3 weeks. After the Letter of Validation, Google may take up to a week to grant final approval. _(Docs [6, 9, 1], medium confidence)_
   - Watch out: Restricted-scope verification and CASA must be renewed every 12 months. Start 60–90 days before expiry.

## Scopes
Google classifies Gmail scopes into three levels. The level decides what review you go through. Most read or modify integrations need restricted scopes.

| Scope | Grants | Level | Consequence |
|---|---|---|---|
| `gmail.labels` | View and edit labels | basic | Brand verification only, if you want your name and logo shown |
| `gmail.send` | Send email as the user | sensitive | OAuth app verification (demo video, justification). No CASA. |
| `gmail.readonly / gmail.metadata` | Read messages and settings, or headers and labels only | restricted | Restricted-scope verification plus annual CASA assessment if data reaches your servers |
| `gmail.modify / gmail.compose / gmail.insert / gmail.settings.basic` | Read, write, send, drafts and settings | restricted | Restricted-scope verification plus annual CASA assessment |
| `https://mail.google.com/` | Full mailbox access, including permanent delete | restricted | Restricted review. Google asks you to request it only if you need permanent deletion. |

## When you get stuck
- **Users see 'Google hasn't verified this app' and new sign-ups stop after 100 users.** The app is unverified and uses sensitive or restricted scopes. The 100-user cap applies for the project's lifetime and cannot be reset. Fix: Complete verification. Keep development in a separate project so you don't use up the production quota. _(Docs [4])_
- **invalid_grant on refresh after about a week.** In Testing status, grants and refresh tokens expire 7 days after consent. Fix: Have users reconnect, or publish to production and get verified. _(Docs [4])_
- **Error 403: org_internal.** The app's user type is Internal, and the user is outside your Google Cloud organization. Fix: Switch the user type to External. _(Docs [4])_
- **Verification sent back for resubmission.** Common causes: scope mismatch, unused scopes, weak demo video, vague justifications, homepage behind a login, missing Limited Use disclosure. Fix: Fix every listed issue, re-record the video if needed and resubmit the form. _(Community [9], medium confidence)_

## Not confirmed yet
- **Exact end-to-end time for Gmail restricted-scope approval** Google gives no Gmail-specific timeline. The CASA figures come from a Google Health API page, and the rest from vendor reports. To resolve: Watch the Verification Center and the emails Google sends to your contact address after you submit.
- **Which CASA tier and fee your app will get** Google assigns the tier based on user count, scopes and other risk signals. To resolve: Google Trust & Safety tells you the tier when the assessment starts. Ask assessors for quotes.
- **Whether you can skip CASA by keeping all Gmail data on the client** The docs say the assessment applies when restricted data is stored or transmitted on servers, but Google decides each case during review. To resolve: Describe your data flow in the submission and confirm with the review team.

## Sources
1. [Restricted scope verification](https://support.google.com/cloud/answer/13464321) (Google Cloud Help). Checked 27 Oct 2026
2. [Choose Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes) (Google for Developers). Checked 27 Oct 2026
3. [When is verification not needed](https://support.google.com/cloud/answer/13464323) (Google Cloud Help). Checked 27 Oct 2026
4. [Manage app audience](https://support.google.com/cloud/answer/15549945) (Google Cloud Help). Checked 27 Oct 2026
5. [Security assessment](https://support.google.com/cloud/answer/13465431) (Google Cloud Help). Checked 27 Oct 2026
6. [App verification (Google Health API)](https://developers.google.com/health/app-verification) (Google for Developers). Checked 27 Oct 2026
7. [Submitting your app for verification](https://support.google.com/cloud/answer/13461325) (Google Cloud Help). Checked 27 Oct 2026
8. [OAuth App Verification overview](https://support.google.com/cloud/answer/13463073) (Google Cloud Help). Checked 27 Oct 2026
9. [Google security review](https://nango.dev/docs/api-integrations/google-shared/google-security-review) (Nango docs). Checked 27 Oct 2026
10. [Managed auth toolkits](https://docs.composio.dev/toolkits/managed-auth.md) (Composio docs). Checked 27 Oct 2026

Wrong or out of date? POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "gmail", "step": 2, "message": "what you saw"} (step is optional), or call the report_problem MCP tool. The next research run checks it.
Followed it? Say how it went: POST https://oauth-guide.akshatsethi.com/api/reports with {"app": "gmail", "outcome": "worked" | "waiting" | "stuck", "step": 3, "message": "what happened"}, or call the report_setup MCP tool.