Compath Docs

Appearance

Google OAuth App Verification Guide ​

This document covers everything needed to submit Compath for Google's OAuth verification so that counselors can connect their Google Calendar accounts without seeing the "unverified app" warning screen.

Scope Decision ​

Compath uses two Sensitive Google OAuth scopes to cover all calendar functionality:

ScopeTierPurpose
https://www.googleapis.com/auth/calendar.eventsSensitiveCreate, update, delete, and watch events
https://www.googleapis.com/auth/calendar.readonlySensitiveList the user's calendars and read events

Both scopes together cover every Google API call the app makes. Neither is in the Restricted tier, so no third-party security audit is required — only the standard Google review (~4–8 weeks, no cost).

See docs/plans/google-scope-reduction.md for the full scope analysis and the one-line code change that enables this.

What Compath Does With Calendar Access ​

OperationGoogle API CallScope Used
List user's calendarsCalendarList.Listcalendar.readonly
Read events (conflict detection)Events.Listcalendar.readonly
Incremental syncEvents.List + sync tokencalendar.readonly
Create session eventEvents.Insertcalendar.events
Update session eventEvents.Updatecalendar.events
Delete session eventEvents.Deletecalendar.events
Setup push notificationsEvents.Watchcalendar.events
Stop push notificationsChannels.Stopcalendar.events

Pre-Submission Checklist ​

Complete every item before clicking "Submit for verification." Google reviewers check all of these.

1. Google Cloud Console — OAuth Consent Screen ​

Navigate to Google Cloud Console → APIs & Services → OAuth consent screen.

  • [ ] App name: Compath
  • [ ] User support email: a monitored inbox (not a personal address)
  • [ ] App logo: 120×120 px PNG, no Google branding elements
  • [ ] Application home page: production URL (e.g. https://compath.app)
  • [ ] Application privacy policy link: live, publicly accessible URL
  • [ ] Application terms of service link: live, publicly accessible URL
  • [ ] Authorized domains: add your root domain (e.g. compath.app) — must match the domains in your privacy policy and homepage URLs
  • [ ] Scopes added:
    • https://www.googleapis.com/auth/calendar.events
    • https://www.googleapis.com/auth/calendar.readonly
  • [ ] Test users: add Google accounts you will use for the demo video

2. Domain Verification in Google Search Console ​

Google requires that every domain listed in your consent screen is verified as belonging to you.

  1. Open Google Search Console and add your domain as a property
  2. Verify ownership via one of:
    • DNS TXT record (recommended) — add the google-site-verification=... record to your DNS
    • HTML file — upload the verification file to your web root
  3. Once verified, the domain becomes selectable in the OAuth consent screen "Authorized domains" field

3. Privacy Policy Requirements ​

Your privacy policy must explicitly address Google user data. The following language covers Google's requirements:

Google Calendar Data

Compath requests access to your Google Calendar to:

  • Display your existing calendar events alongside your Compath sessions so you can identify scheduling conflicts
  • Automatically add, update, and remove counseling sessions from your calendar when they are confirmed, rescheduled, or cancelled

We do not:

  • Read personal calendar events for any purpose other than displaying them to you on Compath's calendar view
  • Share your Google Calendar data with any third parties
  • Use your calendar data to train machine learning models
  • Sell or transfer your calendar data

Compath's use of Google Calendar data complies with the Google API Services User Data Policy, including the Limited Use requirements.

You can revoke Compath's access to your Google Calendar at any time from your Google Account settings or from your Compath profile settings under Settings → Calendar → Disconnect.

4. Demo Video ​

Google requires a screen-recorded video (~2–4 minutes) demonstrating the complete OAuth flow and how calendar data is used in the app.

Required scenes:

  1. A counselor logged into Compath navigating to Settings → Calendar
  2. Clicking "Connect Google Calendar"
  3. The Google OAuth consent screen appearing — showing your app name, logo, and both scope descriptions:
    • "View and edit events on all your calendars"
    • "View your calendars"
  4. The counselor granting permission and being redirected back to Compath
  5. A confirmed counseling session appearing on both Compath's calendar view and the counselor's actual Google Calendar
  6. The counselor disconnecting the calendar from within Compath (revoke flow)

Recording tips:

  • Record at 1080p, keep the file under 500 MB
  • Upload to YouTube as Unlisted (not Private — reviewers must be able to view it without signing into your account)
  • Keep the browser URL bar visible so reviewers can confirm your production domain

Submission Process ​

Step 1: Complete all pre-submission items above ​

Confirm both scopes are listed and all URLs are live and accessible from an incognito window.

Step 3: Click "Submit for verification" ​

A form will appear. Fill it in as follows:

Scope justification for https://www.googleapis.com/auth/calendar.events:

Compath is a mental health counseling platform. When a counselor confirms, reschedules, or cancels a booking, Compath automatically creates, updates, or deletes the corresponding event in their Google Calendar so they have an accurate view of their schedule in one place. The calendar.events scope is required for Events.Insert, Events.Update, Events.Delete, and Events.Watch (push notifications so Compath is notified immediately when the counselor edits events externally).

Scope justification for https://www.googleapis.com/auth/calendar.readonly:

Compath displays the counselor's existing Google Calendar events on its own calendar view so the counselor can see potential scheduling conflicts alongside their Compath sessions. The calendar.readonly scope is required to call CalendarList.List (so counselors can choose which calendar to sync to) and Events.List (to read existing events for display and conflict detection). No external calendar data is stored beyond what is needed to render the current view.

Contact email: use a monitored inbox — Google may ask follow-up questions here

Demo video URL: paste the unlisted YouTube link

Confirm compliance with:

  • Google API Services User Data Policy
  • Limited Use requirements

Step 4: Respond to Google follow-up ​

Because neither scope is Restricted, no third-party security assessment is required. The standard review process applies:

  • Google reviewers check your consent screen, privacy policy, demo video, and scope justifications
  • They may request changes or clarifications — respond within the timeframe specified (usually 7–14 days)
  • Missing the response window resets the review clock

Timeline ​

PhaseTypical Duration
Initial review by Google4–8 weeks
Follow-up responses (if any)1–2 weeks
Total4–10 weeks

This is significantly shorter than the Restricted scope path (3–5 months) because no security assessment is required.

While Awaiting Verification ​

During review the app remains in "Testing" mode:

  • Only accounts listed under Test Users on the consent screen can connect their Google Calendar
  • Up to 100 test users are allowed
  • Test users see a "Google hasn't verified this app" warning screen but can click Continue to proceed
  • Both scopes function normally for test users

To add test users: Google Cloud Console → OAuth consent screen → Test users → Add users

Token Storage ​

Even though a security audit is not required, Google reviewers still expect reasonable data hygiene. Ensure:

  • access_token and refresh_token are encrypted at rest in the calendar_connections table
  • Tokens are never written to logs — verify no middleware logs raw request bodies on the OAuth callback route (/api/v1/calendar/callback)
  • Tokens are transmitted only over HTTPS
  • Tokens are hard-deleted (not soft-deleted) when a user disconnects their calendar

Revocation Flows ​

Google's policy requires users to be able to revoke access from within your app. Verify all three flows work:

1. User-initiated disconnect Settings → Calendar → Disconnect → tokens deleted from DB → webhook channel stopped via Channels.Stop

2. Google-initiated revocation If a user revokes from their Google Account settings, the next API call returns HTTP 401. Compath must handle this by marking the connection as inactive and prompting the counselor to reconnect.

3. Account deletion Deleting a Compath account must stop any active webhook channels and permanently delete all stored OAuth tokens for that user.

Scope Justification Quick Reference ​

ScopeOne-line justification
calendar.eventsCreate, update, and delete counseling session events; receive push notifications via Events.Watch
calendar.readonlyList available calendars for the sync target picker; read existing events for conflict display

Useful Resources ​

  • Google API Services User Data Policy — developers.google.com/terms/api-services-user-data-policy
  • OAuth App Verification FAQ — support.google.com/cloud/answer/9110914
  • OAuth scopes reference — developers.google.com/identity/protocols/oauth2/scopes
  • Google Search Console (domain verification) — search.google.com/search-console

Last updated: