Google Cloud setup

The Bookings addon writes appointments to a Google Calendar using a Service Account — a non-human Google identity that authenticates with a JSON key file you upload to the plugin. This avoids the per-user OAuth consent screen entirely; once the Service Account is set up, the addon authenticates silently forever.

This page is a step-by-step. Plan 15 minutes the first time you do it. You only do it once.

Before you start#

Have ready:

• A Google account. If your business uses Google Workspace, use that account so the calendar lives under the business identity. If not, a free Google account is fine.
• A specific Google Calendar to receive appointments. Either an existing one you already use, or a new one created specifically for bookings. Recommended: create a new calendar called e.g. "Yoursite Appointments" so it is visually separate from personal events.

Part 1 — Create a Google Cloud project#

Google Cloud is the umbrella under which the Calendar API lives. The "project" is just a billing / quota boundary; you will not pay anything to use the Calendar API at the volumes the Bookings addon generates (default Calendar API quotas: 1,000,000 requests/day, more than enough for tens of thousands of bookings).

1. Open console.cloud.google.com.
2. If this is your first visit, accept the terms (and choose a country/timezone).
3. Click the project dropdown at the top of the page (it might say "Select a project" if you have none).
4. Click New Project.
5. Project name: something memorable, e.g. nivosync-bookings. The auto-generated Project ID is fine to keep.
6. Leave Organisation as No organisation unless you're on Workspace and want the project under your org.
7. Click Create. Wait ~15 seconds for the project to provision.
8. Confirm the project dropdown at the top now shows your new project name.

Part 2 — Enable the Calendar API#

1. In the left sidebar, click APIs & Services → Library (or search "Calendar API" in the top search bar).
2. Find Google Calendar API in the results.
3. Click it.
4. Click Enable.
5. Wait ~10 seconds. The page reloads to show the API as enabled with management options.

Part 3 — Create the Service Account#

1. Still in APIs & Services, click Credentials in the left sidebar.
2. Click + Create Credentials at the top.
3. Choose Service account.
4. Service account name: something memorable, e.g. nivosync-bookings-writer. The Service account ID auto-fills from the name.
5. Service account description (optional but helpful future-you): "Writes appointment events to the Yoursite Bookings calendar from the WordPress Bookings addon."
6. Click Create and continue.
7. Grant this service account access to project — leave blank and click Continue. The Service Account does not need any project-level roles; it only needs calendar-level access, which you grant in Part 5.
8. Grant users access to this service account — leave blank and click Done.
9. The Credentials page now lists your new Service Account. Note its email — it looks like nivosync-bookings-writer@nivosync-bookings-12345.iam.gserviceaccount.com. Copy this email; you'll need it twice more.

Part 4 — Download the JSON key#

1. In the Credentials list, click the Service Account email to open its detail page.
2. Click the Keys tab.
3. Click Add key → Create new key.
4. Choose JSON.
5. Click Create.
6. A .json file downloads to your computer. This file is the Service Account's password — treat it as a secret. Do not commit it to git, do not email it, do not paste it into Slack screenshots.

Part 5 — Share the target calendar with the Service Account#

This is the step that grants the Service Account permission to write events. Without it, the addon's API calls will all fail with 403 Forbidden.

1. Open calendar.google.com.
2. In the left sidebar, find the calendar you want bookings to land on (e.g. "Yoursite Appointments").
3. Hover the calendar name, click the three-dot menu, then Settings and sharing.
4. Scroll to Share with specific people or groups.
5. Click Add people and groups.
6. Paste the Service Account email (from Part 3 step 9).
7. Permission: Make changes to events — required so the Service Account can create, update, and delete events. See all event details is read-only and won't let it write.
8. Click Send. Google may warn "No address found for this person" — that's expected (the Service Account is not a real human). Confirm.

Part 6 — Find the calendar ID#

The addon needs the unique ID of the calendar you just shared, not its display name.

1. Still in Settings and sharing for that calendar, scroll to Integrate calendar.
2. Copy the Calendar ID. It looks like:
   • your.email@gmail.com for a personal calendar
   • something@group.calendar.google.com for a separately-created calendar
   • c_random_id@group.calendar.google.com for a Workspace calendar
3. Keep this somewhere temporarily — you'll paste it into the addon settings in Part 7.

Part 7 — Connect the JSON key + Calendar ID in the plugin#

1. In WP admin, NivoSync Bookings → Google Calendar.
2. Service Account JSON: click Upload key file and choose the .json you downloaded in Part 4.
3. The page reads the file in the browser, validates its shape (must have client_email, private_key, project_id), and shows the parsed Service Account email so you can confirm it matches.
4. Click Save key. The file is moved to wp-content/uploads/nivosync-bookings-private/ with an .htaccess (Apache) and a web.config (IIS) that block direct HTTP access. On Nginx the .htaccess does nothing — see the security note below.
5. Calendar ID: paste the Calendar ID from Part 6 into the Calendar ID field.
6. Click Save changes.
7. Click Test connection. If everything is wired correctly, you'll get a green banner "Connection successful — calendar 'Yoursite Appointments' is writable.". If you get an error, see the troubleshooting matrix below.

Troubleshooting matrix#

Once it's working#

Test the full flow before going live:

1. Embed the booking form on a draft page ([nivosync_booking_form]).
2. Open it in a private browser window (so you're not logged-in as admin).
3. Submit a booking with your own email.
4. Verify within 30 seconds: (a) confirmation email arrives in your inbox, (b) event appears on the Google Calendar with correct title/time/attendees, (c) admin notification email arrives.
5. Delete the test event from Google Calendar — verify the slot becomes available again when you re-open the form.

Now move on to designing the form (form builder) and your slot configuration.