Who is this article for?
This article is for Google Workspace super administrators, Cirrus Insight administrators, and security and IT teams setting up an admin-managed connection, also called a service account. A service account lets Cirrus Insight sync email, calendar and task data, send Email Blasts, and read availability for Calendar Scheduling for many users from one Google Cloud service account, so each user does not have to sign in and grant consent individually.
If your users connect their own Gmail accounts instead, see the individual connection article.
Why does Cirrus Insight need a service account?
Cirrus Insight reads and writes Google Workspace data through Google's public APIs (Gmail API, Google Calendar API, Google Tasks API and, optionally, the People API). For an admin-managed connection, Google requires:
- A Google Cloud project in your organization with those APIs enabled
- A service account in that project, which is the identity Cirrus Insight uses
- A JSON key for that service account, which you upload to Cirrus Insight once
- A domain-wide delegation grant in the Google Admin console that authorizes the service account's client ID for a specific list of OAuth scopes
With that in place, Cirrus Insight uses the key to request short-lived access tokens on behalf of each user it syncs. You control what it can do with the scope list (Step 3) and which users it is used for with the domain list and user-level sync settings in Cirrus Insight (Step 4).
Security note. Domain-wide delegation grants the service account access to the authorized scopes for every user in your Workspace domain, not only the users you enable in Cirrus Insight. Google recommends granting only the scopes an application needs and reviewing delegated clients regularly. The
Security and data access section explains what Cirrus Insight does with the grant and how to keep it minimal.
Features you can manage with a service account
| Cirrus Insight feature |
What the service account does |
| Email Sync |
Reads Inbox and Sent mail for enabled users and files matching messages to Salesforce. Optionally applies a "Filed with CI" Gmail label. |
| Email Blast Sync |
Files Email Blasts that were sent from Gmail to the matching Salesforce records. |
| Email Blasts (sending) |
Sends Email Blasts from the user's Gmail account. Service-account sending must be enabled for your organization by Cirrus Insight support; otherwise blasts are sent over each user's individual connection. |
| Calendar Sync |
Reads Google Calendar events and files them to Salesforce. With two-way sync enabled, also creates and updates Google Calendar events from Salesforce. Optionally applies a "Filed with CI" label to synced events. |
| Calendar Scheduling |
Reads free/busy availability and creates calendar events for booked meetings. |
| Meeting AI |
Reads calendar events to prepare meeting research and to schedule the recording assistant. |
| Task Sync |
Reads Google Tasks and files them to Salesforce; creates Google Tasks from Salesforce when two-way sync is enabled. |
| Email alias resolution |
Reads each enabled user's own alias addresses so email sent from an alias is matched to the correct Contact or Lead. Enabled on request by Cirrus Insight Support. |
Before you begin
You will need:
- Google Workspace super administrator rights. Google only allows super administrators to authorize domain-wide delegation.
- Google Cloud access in the same organization, with permission to create a project (or use an existing one), enable APIs, and create a service account and key. The Project Owner or Editor role is sufficient. If your organization separates Workspace and Cloud administration, you will need both people.
- Cirrus Insight administrator access to your organization's Admin Dashboard.
⚠️ Key creation may be blocked by policy. If your Google Cloud organization was created on or after May 3, 2024, Google's security baseline enforces the organization policy Disable service account key creation by default, and older organizations may have enabled it manually. If so, your Google Cloud organization administrator must allow key creation for the project before Step 2 can be completed. Check this before you start; it is the most common reason the setup stalls.
Decide which Cirrus Insight features you will deploy through the service account. The scope list in Step 3 depends on it.
Step 1: Create the Google Cloud project and enable the APIs
Create or select a project
- Sign in to the Google Cloud console (console.cloud.google.com) with an account in your Workspace organization.
- In the project picker at the top of the page, select New project.
- Name it (for example, Cirrus Insight Sync). Make sure Organization and Location point to your Workspace organization, not No organization. A service account in a project outside your organization cannot be delegated for your domain.
- Select Create, then select the new project in the picker.
You can reuse an existing project. The service account and key are what matter, not the project.
Enable the APIs
Go to APIs & Services → Library, search for each API below, and select Enable.
| API |
Enable when you use |
Notes |
| Gmail API |
Email Sync, Email Blasts, Email Blast Sync |
Required for any email feature. |
| Google Calendar API |
Calendar Sync, Calendar Scheduling, Meeting AI |
Also used by the connection test in Cirrus Insight, so enable it even for an email-only deployment. |
| Google Tasks API |
Task Sync |
Omit if you do not sync tasks. |
| People API |
Email alias resolution |
Optional. If it is not enabled, alias resolution is skipped and sync continues. |
Enabling an API does not grant any access by itself; it only allows this project to call it. Access is granted in Step 3.
Step 2: Create the service account and its key
Create the service account
- In the Google Cloud console, go to IAM & Admin → Service Accounts and make sure your project is selected.
- Select Create service account.
- Enter a Service account name (for example, cirrus-insight-sync). Google generates the service account ID and email address (
name@project-id.iam.gserviceaccount.com) from it; the ID cannot be changed later.
- Optionally add a description, then select Done.
Skip both optional steps in the wizard ("Grant this service account access to project" and "Grant users access to this service account"). IAM roles in Google Cloud control access to Cloud resources only; they have no effect on Gmail or Calendar data and are not needed by Cirrus Insight.
Create the JSON key
- On the Service Accounts page, select the service account's email address.
- Open the Keys tab.
- Select Add key → Create new key.
- Choose JSON and select Create. The key file downloads to your computer. This is the only copy; Google never shows it again.
- Keep the file until you have uploaded it to Cirrus Insight (Step 4), then delete your local copy.
Key hygiene. The JSON key is a long-lived credential. Treat it like a password: do not email it, do not commit it to source control, and delete the download after upload. Cirrus Insight stores it encrypted and never returns it to the browser. To rotate the key, create a new one, upload it to the existing Cirrus Insight service account and save, then delete the old key from the Keys tab. If your organization enforces a key-expiry policy, record the expiry date: when the key expires, every user synced through the service account stops syncing at the same time.
Copy the client ID
- Still on the service account's page, open the Details tab and expand Advanced settings.
- Under Domain-wide delegation, copy the Client ID (a 21-digit number). It is the same value as the service account's Unique ID and as
client_id inside the JSON key file.
Step 3: Authorize domain-wide delegation
- Sign in to the Google Admin console (admin.google.com) as a super administrator.
- Go to Menu → Security → Access and data control → API controls.
- Scroll to the bottom and select Manage Domain Wide Delegation.
- Select Add new.
- In Client ID, paste the client ID from Step 2.
- In OAuth scopes, paste the comma-separated list for the features you will use (see below), with no spaces.
- Select Authorize.
- Find the new entry in the list, select View details, and confirm every scope is listed. If one is missing, select Edit, add it, and authorize again.
Changes usually apply within minutes but can take up to 24 hours. If your organization has multi-party approval enabled, a second super administrator must approve the grant before it takes effect.
⚠️ Use the numeric client ID, not the service account email. If Authorize fails, the client ID is usually mistyped, or a scope in the list is misspelled or duplicated.
Required OAuth scopes by feature
Authorize only what you need for the features you deploy.
| Cirrus Insight feature |
Required scopes |
| Email Sync |
https://www.googleapis.com/auth/gmail.modify |
| Email Blast Sync |
https://www.googleapis.com/auth/gmail.modify (same as Email Sync; nothing extra) |
| Email Blasts (sending) |
https://www.googleapis.com/auth/gmail.modify |
| Calendar Sync |
https://www.googleapis.com/auth/calendar |
| Calendar Scheduling |
https://www.googleapis.com/auth/calendar |
| Meeting AI |
https://www.googleapis.com/auth/calendar |
| Task Sync |
https://www.googleapis.com/auth/tasks |
| Email alias resolution |
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile |
| Connection test and "Connected" status in Cirrus Insight |
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.readonly |
What each scope is used for:
gmail.modify: read messages in Inbox and Sent (Email Sync, Email Blast Sync); create and apply the "Filed with CI" label; send Email Blasts as the user; register Gmail change notifications so new mail is picked up promptly. Gmail has no narrower scope that covers both reading and labeling.
calendar: read calendars and events (Calendar Sync, Calendar Scheduling, Meeting AI); read free/busy availability for Scheduling; create, update and delete events for Salesforce-to-Google sync and for Scheduling bookings; register calendar change notifications.
calendar.readonly: a strict subset of calendar. It is listed because the Cirrus Insight connection test requests both scopes together; if it is missing, Run Test and the Connected status fail even though sync itself would work.
tasks: read, create and update Google Tasks (Task Sync).
userinfo.email / userinfo.profile: read the enabled user's own primary address and alias addresses through the People API. No mailbox content. These scopes are needed when users send email from an alias address: without them, Cirrus Insight can only see the primary address and cannot match alias mail to the right Contact or Lead. Alias support is enabled on request by Cirrus Insight Support; include the two scopes in your delegation so it can be switched on without a further change on your side.
Scope lists by deployment
Copy the line that matches your deployment into the OAuth scopes field.
Email and Calendar Sync, Email Blasts, Calendar Scheduling, Meeting AI (most common):
https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile
All of the above plus Task Sync:
https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/tasks,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile
Calendar features only (Calendar Sync, Scheduling, Meeting AI; no email features):
https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile
Email features only (Email Sync, Email Blasts; no calendar features):
https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile
The email-only list still carries the two calendar scopes because the Cirrus Insight connection test reads a calendar.
Step 4: Connect the service account in Cirrus Insight
You need a Cirrus Insight administrator login. All steps are in the Admin Dashboard at home.cirrusinsight.com.
Add your email domains first
Cirrus Insight matches users to a service account by email domain, so the domains must exist before the service account can be saved.
- Sign in and open the admin settings for your organization. In the left navigation, select Domains.
- Select Add Domain, enter one email domain (for example,
acme.com), and save it. Repeat for every domain whose mailboxes this service account will cover.
A user whose email domain is not in this list is never picked up by the service account.
Add the service account
- In the left navigation select Advanced, then Authentication → Service Accounts.
- Select + Add. A panel opens on the right.
- Under Email Providers, select Connect using Google.
- Complete the form:
- Service Account JSON (required): select the JSON key you downloaded in Step 2. If the file picker shows the
.json file greyed out, change the picker's file-type filter to All Files. Once selected, the file's contents appear in a text box below the field for review. Cirrus Insight reads the service account's email address from the file and uses it as the account name.
- Domain List (required): select every domain this service account should cover.
- Test Account: the primary email address of one active Workspace user in one of the selected domains. The address must belong to a selected domain.
- With a Test Account entered, a Run Test link appears inside the field. Select it and wait for Account tested successfully. If you see Test failed, re-check Steps 2 and 3 before saving.
- Select Save at the top of the panel.
About the Test Account. Run Test requests a token for the Test Account and lists that user's calendars, which confirms the key, the delegation entry and the Calendar scopes. It does not check the Gmail or Tasks scopes, and if the field is empty the test can pass before delegation is set up, so always provide one. To confirm email or task access, enable the feature for one user and check that user's sync status.
The service account appears in the Service Accounts list with its Name (the service account's ...iam.gserviceaccount.com address), Data Source (Gmail) and Status. Connected means the connection check passed when the account was last saved. If the key or the delegation is removed later, the status does not change until the account is saved again, but sync for every covered user stops.
To edit the service account later (for example, to change the domain list or upload a rotated key), select it in the list. Leaving Service Account JSON empty on an existing account keeps the stored key.
Security and data access
What Cirrus Insight does with the grant
- Cirrus Insight requests tokens only for users who are enabled for a sync feature in the Admin Dashboard (or for whom a Scheduling page, Email Blast or Meeting AI request is being processed) and whose domain is in the service account's domain list. It never enumerates your directory through the service account.
- Each token is requested with only the scopes the current operation needs: Gmail scopes for email work, Calendar scopes for calendar work, Tasks for tasks. Tokens are short-lived (one hour) and are not stored.
- The JSON key is encrypted at rest in Cirrus Insight and is never sent back to a browser or exported.
- Cirrus Insight writes to Google only where the feature calls for it: the "Filed with CI" label on synced messages and events (can be turned off), events created for Salesforce-to-Google calendar sync and for Scheduling bookings, Email Blast sends, and Google Tasks created by Task Sync.
What the grant allows in principle
Domain-wide delegation is domain-scoped by design. Google does not allow a delegated client to be restricted to an organizational unit, a group, or a list of users; a delegated client can request tokens for any user in the domain for the authorized scopes. The controls you have are:
- Scopes. Authorize only the scopes for the features you deploy. Narrow the list when features change.
- Review. Google recommends a periodic review of delegated clients under Security → API controls → Manage Domain Wide Delegation, removing scopes that are no longer required and deleting clients no longer in use.
- Key control. The key lives in your project. Deleting the key, or the service account, revokes Cirrus Insight's access immediately. Removing the delegation entry does the same.
- Audit. Token requests and API calls made by the service account appear in Google's OAuth log events and in the Gmail and Calendar audit logs in the Admin console, attributed to the service account's client ID.
Recommended operational policy
- Create a dedicated project and service account for Cirrus Insight; do not reuse a service account that has other roles or keys.
- Name the project and service account so the purpose is obvious in audits (for example, cirrus-insight-sync).
- Record the key creation date and rotate the key at least annually, or when administrators change.
- Re-check the scope list whenever you add or remove a Cirrus Insight feature.
Need help?
If you have questions about this article, or run into challenges while setting up your service account, contact Cirrus Insight Support. We are happy to help.
Frequently asked questions
What is a Google Workspace service account in Cirrus Insight?
It's an admin-managed connection that lets Cirrus Insight sync Gmail, Calendar and Tasks, send Email Blasts and read Scheduling availability for many users from one Google Cloud service account, without each user signing in.
What do I need to set up a Cirrus Insight Google Workspace service account?
Google Workspace super administrator rights, Google Cloud access to create a project, service account and key, and Cirrus Insight admin access.
Which Google APIs does Cirrus Insight need enabled?
Gmail API for email features, Google Calendar API for calendar features and the connection test, Google Tasks API for Task Sync, and optionally the People API for email alias matching.
What OAuth scopes do I authorize for Cirrus Insight domain-wide delegation?
Most orgs use gmail.modify, calendar, calendar.readonly, userinfo.email and userinfo.profile. Add the tasks scope if you use Task Sync.
Why can't I create a service account key for Cirrus Insight in Google Cloud?
Your organization may enforce the "Disable service account key creation" policy, which is on by default for Google Cloud organizations created on or after May 3, 2024. A Cloud organization admin must allow key creation for the project.
Can I limit the Cirrus Insight service account to certain Google users?
Not within Google: domain-wide delegation applies to the whole domain. Cirrus Insight only requests access for users enabled for a feature and in the domains you list, and you control access by limiting scopes and the key.
How do I revoke Cirrus Insight's Google Workspace access?
Delete the service account's key, the service account itself, or its domain-wide delegation entry. Any of these revokes access immediately.