Google Workspace API scopes

Overview

This article describes the integration between Opensense and Google Workspace Directory. The integration is used only to retrieve user metadata, and to deploy personalized email signatures from the Opensense platform.

Although the Opensense Marketplace app includes a broad set of permissions, only the scopes listed below are authorized and used in this deployment.

Integration components

App name: Opensense (formerly SenderGen)
Source: Google Workspace Marketplace
Publisher: Opensense Inc.
Purpose: Retrieve directory metadata, and deploy email signatures
Integration type: OAuth 2.0, through scoped API access
Data flow: One-way: Google Workspace to Opensense

Purpose of access

The integration reads user and group metadata from Google Directory, and writes signatures to Gmail, to support:

Signature personalization
Insert user-specific fields (for example, full name, title, and phone) into templated HTML signatures.
Group-based logic
Apply signature variations based on group membership (for example, different designs for the Sales and Support teams).
OU-based filtering
Use organizational units (OUs) to define user targeting or inclusion rules.
Signature deployment
Write finalized signatures to user mailboxes, primary addresses, and send-as aliases, through the Gmail API.

Authorized API scopes

Only these API scopes are granted. API scopes are permission identifiers that Google uses to control what data an application can access. They aren’t navigable URLs. For a full reference of the available Gmail API scopes, see Google’s Choose Gmail API scopes.

API scope	Access	Purpose
`https://www.googleapis.com/auth/admin.directory.user.readonly`	Read-only	Pull user attributes, like name, title, and department.
`https://www.googleapis.com/auth/admin.directory.group.readonly`	Read-only	Identify group memberships, to assign the correct signature template.
`https://www.googleapis.com/auth/admin.directory.orgunit.readonly`	Read-only	Allow filtering or targeting based on the user's OU placement.
`https://www.googleapis.com/auth/gmail.settings.basic`	Read/write	Edit email signatures for the user's primary account.
`https://www.googleapis.com/auth/gmail.settings.sharing`	Read/write	Edit email signatures for the user's alias accounts.

Directory scopes are strictly read-only. The gmail.settings.basic and gmail.settings.sharing scopes can write, but are limited to signature deployment. Opensense can’t access, read, or change email content, routing, or any other Gmail settings.

Excluded permissions (not utilized)

Although they’re presented during app installation, these permissions are not authorized, granted, or used:

Access sensitive mail settings
Control mail routing
Filter or delegate Gmail
Access Gmail message content

These are default scopes in the Opensense app manifest, but they’re explicitly excluded during deployment through scoped OAuth configuration.

Security and access controls

Access control: A Google Workspace Super Admin authorizes and manages the integration. Permissions are enforced with granular OAuth scope control in the Admin console, and app access is restricted to the five API scopes listed above.
No access to email content or controls: Opensense can't view, alter, or route email messages. The platform has no access to Gmail accounts, settings, or message data beyond signature deployment.
Data handling: Data is accessed through secure, encrypted API calls (TLS). No directory data is written back to Google Workspace. Opensense processes only non-sensitive metadata, for display purposes.
Revocation and audit: Admins can revoke access at any time, in the Admin console under Security > Access and data control > API controls. Audit logs and app access reviews are supported natively in Google Admin settings.

IT security review checklist

Confirm scoped access. Validate that only the five API scopes listed above are authorized.
Review admin approval. Make sure that a Super Admin has approved and restricted the Marketplace app.
Review access control settings. Confirm that permissions for Gmail message content, routing, or sensitive settings aren’t turned on.
Turn on audit logging. Consider turning on API access logs, for periodic internal compliance reviews.
Request an OAuth scope summary (optional). Contact Opensense or your admin for a detailed list of active scopes, if you need it for an internal audit or SOC 2 or ISO 27001 reviews.
Review vendor security documentation. See the Opensense Security Overview.

Troubleshooting and support

App not syncing users?: Check that the organizational units or groups are accessible to the app.
Signatures not deploying?: Confirm that the gmail.settings.basic and gmail.settings.sharing scopes are authorized, and that domain-wide delegation is turned on for the Opensense service account.
Aliases not receiving signatures?: Verify that gmail.settings.sharing is authorized, and that domain-wide delegation is configured correctly in the Admin console.
Unexpected permissions?: Check the scopes again in the Admin console, under Security > Access and data control > API controls (formerly Apps > App access control).
Need help?: Contact Opensense Support at help@opensense.com for integration guidance or help with reconfiguration.

What’s next

How does Opensense work with Google Workspace?
Google Workspace integration overview (change request)
Google Add-on deployment overview (change request): the add-on’s own OAuth permissions.