Google Workspace Authorization Guide

This guide helps a Google Workspace administrator allow Town for an approved user population, and maps common Google authorization errors to the setting that is the likely cause.

Town uses per-user OAuth authorization. Town does not use Google Workspace domain-wide delegation. Two separate controls are involved:

An admin approval does not create a Town account or add a user to a Town team. A user approval does not override a Workspace policy.

Town’s OAuth client

Use this exact client ID when configuring Town in Google Admin.

Choose an app access policy

Google Workspace provides four app access settings:

For a pilot, use one of two patterns:

• Least-data pattern — set Town to Specific Google data for the pilot population and add the complete base set. If your organization approves Drive or Contacts, add only the applicable bundle.
• App-trust pattern — set Town to Trusted for the pilot population, if your organization accepts the broader app policy.

Base permission set

Town requests the base set when a user connects their primary Google Workspace account. It supports identity, Gmail, Calendar, calendar availability, calendar discovery, and Workspace group expansion.

Notes:

• gmail.modify is classified as a high-risk Gmail scope in Google Admin. It is required for Town’s current Gmail capabilities, including actions that only read mail.
• The Cloud Identity Groups scope lets Town expand a Workspace group for calendar workflows. It does not give Town domain-wide administrator access.
• Do not omit the sign-in scopes — Town always requests them to identify the connecting account, even when your review concerns only Gmail or Calendar data.
• Room-calendar directory access is a separate, admin-restricted capability. Do not add an Admin Directory room scope unless that feature is approved separately.

Optional capability bundles

Town uses progressive authorization for the primary account: a user can connect Gmail and Calendar without Drive or Contacts. With Specific Google data, allow an optional bundle before a user enables that feature.

Drive, Docs, Sheets, and Slides

Add all four scopes before a user enables the Drive integration. Google classifies the Drive and Docs scopes as high risk; they permit read and write actions in the connected user’s Google files.

Google Contacts

Contacts is a separate optional enhancement. Add all three scopes before a user enables it.

Secondary Google accounts

A new secondary Google connection requests the base set and the Drive bundle by default (Contacts remains a separate opt-in). If your organization uses Specific Google data, allow the Drive bundle before a user adds a secondary Google account.

Configure Town in Google Admin

Use an administrator account with the Security settings privilege.

Admin path: Security → Access and data control → API controls → Manage App Access

1. Under Configured apps, select Configure new app.
2. Enter Town’s production OAuth client ID (above).
3. Select the result named Town and confirm the client ID matches exactly.
4. If the policy applies to all users, keep the top organizational unit at Scope. Otherwise, select the organizational unit(s) that contain the pilot users.
5. Select Specific Google data or Trusted according to your approved decision.
6. For Specific Google data, add every scope in the base set, plus only the approved optional bundles.
7. Review the client ID, organizational units, access setting, and scopes, then select Finish.

Notes on scope of the policy:

• The initial Configure new app wizard offers organizational units, not configuration groups. After the app exists, open its app information page and expand Access to Google data — in supported Google Admin editions an admin can then target a group. Verify this option is available in your Workspace edition before designing a group-based policy.
• If a child organizational unit already has an app policy, a later change at the top organizational unit does not replace that child policy.
• A Town team is not a Google Workspace policy boundary. Google applies the OAuth policy to the selected Workspace users, not to Town team membership.
• Configure Town explicitly by client ID; do not depend on your fallback policy for unconfigured apps.
• Changes can take up to 24 hours to propagate (usually sooner).

Verify the configured list

The access-level setup screen can show scopes the app requested in the past, which can be broader than the current policy. Open View details for Town to verify the scopes Google currently applies.

If Town adds a scope in the future, Town tells customers before users can enable the related capability — with Specific Google data, update the allowlist before the new request can succeed.

Context-Aware Access

If your organization applies Context-Aware Access levels to Workspace API access, a level assigned to a Google service can block Town’s API calls even after the app access policy allows Town.

If an exemption is required, follow Google’s exemption workflow :

1. Configure Town by OAuth client ID and set it to Trusted for the approved organizational units.
2. Select Exempt from having API access blocked by Context-Aware Access levels in the Town app access policy.
3. Verify the exemption applies to the pilot users, then test from a device and network that represent the pilot policy.

If your organization does not use Context-Aware Access for Workspace API access, do not add an exemption.

Error-to-action matrix

The same screen can have more than one cause. Treat these mappings as likely causes, not proof — verify the effective user policy and the exact OAuth request.

Also verify whether the user selected every required permission on Google’s consent screen — an incomplete user grant can look similar to an admin-policy failure after sign-in.

Workspace-side recovery

For access_not_configured, admin_policy_enforced, or a scope failure:

1. Record the affected user’s primary email address and identify their organizational unit (and any configuration group that changes Town’s app access policy).
2. In Manage App Access, find Town by the production OAuth client ID and open View details to verify the effective access setting for that user population.
3. If the setting is Blocked, apply the approved Specific Google data or Trusted policy.
4. If the setting is Specific Google data, compare every requested scope with the base and optional tables above.
5. If the setting is Limited, review each requested Google service — a restricted service can block the request.
6. If Context-Aware Access applies, verify Town is Trusted with the Context-Aware Access exemption selected.
7. Verify Gmail is provisioned for the user.
8. Ask the user to start a new Town connection in a supported browser, selecting every required permission.

Do not use repeated reconnect attempts as a substitute for checking the policy — a blocked or incomplete policy will produce the same failure again.

When to contact Town

The customer controls Workspace policy; Town controls the production OAuth project, consent-screen configuration, enabled Google APIs, and the scope request the product sends. Contact Town support when:

• The app name, publisher, or verification information looks incorrect, or Google reports the app is not verified.
• A Google API returns accessNotConfigured for Town’s Cloud project.
• The consent screen requests a scope that is not in the tables above.
• The client ID Google displays does not match the one printed in this guide.
• The error continues after the effective Workspace policy and user grant are verified.

Helpful evidence: the exact error code and text, date/time and time zone, the affected user (or an approved identifier), the client ID Google displayed, the Google service that failed, the browser used, a screenshot with tokens and unrelated personal data removed, the effective app access setting and target organizational unit or group, and whether Context-Aware Access applies.

Verification checklist

Before the pilot starts:

• The configured app is named Town and matches the production OAuth client ID above (reviewed by client ID, not app name alone).
• View details shows Specific Google data or Trusted for the pilot users.
• If Specific Google data is used, every base scope is present — plus the Drive bundle (four scopes) and/or Contacts bundle (three scopes) if approved, and the Drive bundle if secondary Google accounts will be added.
• If Context-Aware Access applies, Town is Trusted and its app access policy contains the Context-Aware Access exemption.

Then run a controlled user test: one pilot user connects in a supported browser, selects every required permission, and confirms Town shows the account as connected, can list calendars, read free/busy availability, and complete a Gmail draft test. Test each approved optional feature only after its scope bundle is allowed.

Google references

• Control which apps access Google Workspace data 
• Control which third-party and internal apps access Google Workspace data 
• About Context-Aware Access 
• Exempt trusted third-party apps from Context-Aware Access API blocks 
• Handle Google OAuth errors