Skip to navigation
Communication & Collaboration

Google Calendar

View as Markdown

Automate calendar sharing, calendar handovers, and Gmail delegation across your Google Workspace from within your workflows, with no per-user sign-in.

At a glance

What Google Calendar isGoogle Workspace’s calendar service. This integration also covers Gmail delegation, since both are managed for a Workspace user.
What Atomicwork supportsCall API: call any Google Calendar or Gmail delegation API from a workflow, acting as any user in your Workspace.
AuthenticationGoogle service account (JSON key) with Google Workspace domain-wide delegation
Configured inAtomicwork → Settings > Enterprise integrations > App store > Google Calendar
Access requiredOrg admin on Atomicwork; access to Google Cloud console to create a service account; Google Workspace super admin to set up domain-wide delegation

Overview

Most calendar integrations only work on the calendar of the person who signed in. IT teams often need more: share one person’s calendar with someone else, hand over a leaver’s calendar and mailbox to their manager, or remove that access later.

This integration uses a Google service account with domain-wide delegation. Your Google Workspace admin allows the service account to act as users in your domain. Each workflow step then says which user to act as (Act as user), and Atomicwork calls the Google API as that user.

Approvals, tickets, timers, and access removal are handled by your Atomicwork workflow. Google Calendar and Gmail make the actual change.

What you can automate

Call any Google Calendar or Gmail delegation API in workflows

The Call API capability lets a workflow call any Google Calendar endpoint, and the Gmail delegate endpoints, as any user in your Workspace. For example:

  • Request access to a calendar: a user asks for access to someone’s calendar, the owner approves, and the workflow shares the calendar with the requester.
  • Leaver handover: when someone leaves, give their manager access to their calendar and mailbox, then remove it automatically after a set time (for example, 14 days).
  • Remove access: take away calendar sharing when someone changes team or when temporary access ends.
  • Executive assistant access: give an assistant edit access to an executive’s calendar.
  • Out of office: when leave is approved, block the user’s calendar.
  • New joiner: add orientation and training meetings to a new hire’s calendar.
  • Access review: list who has access to a calendar, for audits.

These are just examples. Anything in the Google Calendar API or the Gmail delegates API can be called this way, as long as the matching scope is allowed (see Scopes).

Before you begin

Make sure you have the following before you start, so setup runs end to end without interruption:

  • Org admin access on Atomicwork.
  • Access to the Google Cloud console to create a project, a service account, and a JSON key.
  • A Google Workspace super admin to set up domain-wide delegation in the Google Admin console.
  • The email of a real user in your Workspace to use as the Admin email for testing the connection. An admin account is recommended.

Scopes

Scopes decide what the service account can do in your Workspace. You add them in the Google Admin console when you set up domain-wide delegation. Add only the scopes your workflows use.

ScopeRequired?Purpose
https://www.googleapis.com/auth/calendarRequiredUsed to test the connection, and for all calendar work: sharing, events, and access lists.
https://www.googleapis.com/auth/gmail.settings.sharingOnly for Gmail delegationAdd and remove Gmail delegates (give someone access to another person’s mailbox).

How scopes are used:

  • When you connect: Atomicwork checks only the calendar scope.
  • When a workflow runs: each call asks Google only for the scope it needs. Gmail URLs use the Gmail scope; all other URLs use the calendar scope.
  • Calendar only: if you allow only the calendar scope, you can connect and use calendar calls. Only Gmail calls fail.

Example: leaver handover. A workflow that hands over a leaver’s calendar and mailbox to their manager needs both scopes:

https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/gmail.settings.sharing

Setup

To set up the integration, create a service account in Google Cloud, allow it in Google Admin, connect it in Atomicwork, and verify the connection. You can update or rotate the JSON key later.

1. Create a service account and JSON key in Google Cloud

  1. Go to the Google Cloud console and select or create a project.
  2. Go to APIs & Services > Library and enable the Google Calendar API. If you use Gmail delegation, also enable the Gmail API.
  3. Go to IAM & Admin > Service Accounts > Create service account.
  4. Enter a name (for example, atomicwork-calendar) and click Create and continue. You don’t need to give it any Google Cloud roles. Click Done.
  5. Open the service account and copy its Unique ID (the client ID). You’ll need it in the next step.
  6. Go to the Keys tab and click Add key > Create new key. Select JSON and click Create. The key file downloads to your computer.

Important: The JSON key gives access to your Workspace. Store it securely and never share it in chat or screenshots. If it is exposed, delete the key in Google Cloud and create a new one.

2. Set up domain-wide delegation in Google Admin

  1. Sign in to the Google Admin console as a super admin.
  2. Go to Security > Access and data control > API controls.
  3. Under Domain-wide delegation, click Manage domain-wide delegation > Add new.
  4. In Client ID, paste the service account’s Unique ID from step 1.
  5. In OAuth scopes, paste the scopes you need, comma-separated (see Scopes).
  6. Click Authorize.

Note: Changes in Google Admin can take a few minutes to apply. If the test fails right after you add a scope, wait a few minutes and try again.

3. Connect in Atomicwork

  1. In Atomicwork, go to Settings > Enterprise integrations > App store > Google Calendar.
  2. In Service account JSON key, paste the entire content of the JSON key file, from { to }. The private key alone is not enough.
  3. In Admin email, enter the email of a real user in your Workspace, for example admin@yourcompany.com.
  4. Click Test to validate the connection.
  5. Click Connect to activate the integration.

About the Admin email: it is used only to test the connection. Atomicwork acts as this user and reads their calendar list, which is read-only and changes nothing. It is never used to run workflow steps.

4. Verify the connection

Click Test on the Google Calendar connection. The test checks that the JSON key is valid, that domain-wide delegation is set up, and that the calendar scope is allowed.

  • Success: a confirmation appears: “Connection tested. You’re all set!” Click Connect to finish.
  • Failure: an error appears explaining what is wrong, for example an invalid key or missing domain-wide delegation.

If the test fails, see Troubleshooting.

5. Update or rotate the JSON key

To change the key later, for example after rotating it in Google Cloud:

  1. Go to Settings > Enterprise integrations > App store > Google Calendar and click Edit.
  2. Paste the full content of the new JSON key file. If you leave the key unchanged, the saved key is kept.
  3. Click Connect again to save.
  4. Delete the old key in Google Cloud.

Using Call API in a workflow

Each Call API step takes these inputs:

FieldRequiredDescription
HTTP methodYesGET, POST, PUT, PATCH, or DELETE.
API URLYesFull Google API URL, for example https://www.googleapis.com/calendar/v3/calendars/primary/acl.
HeadersNoExtra headers as JSON. The sign-in header is added for you.
Request bodyNoJSON body for the request.
Act as userYesEmail of the Workspace user the call runs as, for example the calendar owner.

Example: share a calendar after the owner approves. Acting as the owner, give the requester read access to the owner’s calendar:

  • HTTP method: POST
  • API URL: https://www.googleapis.com/calendar/v3/calendars/primary/acl
  • Request body: {"role": "reader", "scope": {"type": "user", "value": "requester@yourcompany.com"}}
  • Act as user: owner@yourcompany.com

The response includes an id for the new access rule. Save it if you want to remove the access later with a DELETE call to .../calendars/primary/acl/{id}.

Example: give a manager access to a leaver’s mailbox.

  • HTTP method: POST
  • API URL: https://gmail.googleapis.com/gmail/v1/users/me/settings/delegates
  • Request body: {"delegateEmail": "manager@yourcompany.com"}
  • Act as user: leaver@yourcompany.com

To remove it later, send a DELETE call to .../settings/delegates/manager@yourcompany.com, acting as the same user.

Behaviors and limits

Design your workflows around these behaviors when using Call API:

  • Act as user is required. Every call must name the Workspace user to act as. There is no fallback to the Admin email.
  • One scope per call. Each call asks Google only for the scope its URL needs. A call whose scope isn’t allowed in Google Admin fails, even if other calls work.
  • Suspended or deleted users. Google may not allow acting as a suspended or deleted user. For leavers, set up the handover before the account is suspended.
  • Gmail delegate limits. Google sets its own rules for Gmail delegates, for example the delegate must be in the same organization. See Gmail delegates.
  • Pagination. Google list endpoints return a nextPageToken. Pass it as pageToken to get the next page.
  • Rate limits. Google applies usage limits per project and per user. If you get a 403 or 429 with a rate-limit reason, retry later.

Troubleshooting

If you hit an issue, check the message against the table below:

ErrorCauseResolution
”Google service account JSON is invalid” or “Google service account JSON must include …”The pasted key is not the full JSON key file, or is missing fields.Paste the entire content of the JSON key file, from { to }.
”The service account key is invalid or has been deleted.”The key was deleted or disabled in Google Cloud, or is not a valid key.Create a new JSON key in Google Cloud and update the connection.
”The user … was not found in your Google Workspace.”The Admin email, or the Act as user email, is not a user in your Workspace.Check the email and use a real, active Workspace user.
”Domain-wide delegation is not set up for this service account, or the scope … is not added.”Domain-wide delegation isn’t set up for the service account’s client ID, or the scope shown is missing. Google returns the same error for both.In Google Admin, go to Security > Access and data control > API controls > Domain-wide delegation and add the scope for the service account’s client ID.
”Google Calendar access was denied for the admin email.”Google accepted the sign-in but refused calendar access.Check that the Google Calendar API is enabled and the calendar scope is added in domain-wide delegation.
”Act as user is required for Google Calendar Call API requests.”A Call API step has no Act as user email.Add the email of the user the call should run as.
403 from a Gmail URLThe Gmail scope isn’t added, or the Gmail API isn’t enabled.Add https://www.googleapis.com/auth/gmail.settings.sharing in domain-wide delegation and enable the Gmail API.

Supported workflow actions

Once connected, you can automate the following Google Calendar actions within your Atomicwork workflows:

ActionDescription
Call APIExecute a generic API call to any Google Calendar or Gmail delegation endpoint, acting as a Workspace user.