If you are setting up a WordPress plugin that connects to Google Calendar, you will need a service account. A service account is a credential that lets a server-side application communicate with Google’s APIs without requiring a person to log in through a browser.
This guide covers the complete setup from scratch: creating a Google Cloud project, enabling the Calendar API, creating the service account, and uploading the JSON key file to your plugin. It also covers why this approach is more reliable than OAuth, how to use a dedicated booking calendar, and what to do if something goes wrong.
What this guide covers
- Service account vs OAuth — why this approach is more reliable
- Steps 1–2: Create a Google Cloud project and enable the Calendar API
- Steps 3–5: Create the service account and download the JSON key
- Steps 6–7: Share your calendar and find your Calendar ID
- Step 8: Upload to your WordPress plugin
- Using a dedicated booking calendar (recommended)
- What the service account can and cannot access
- Troubleshooting common problems
Time required: approximately 15–20 minutes. You only need to do this once — the credentials do not expire.
Service account vs OAuth — why this approach is more reliable
Most Google Calendar integrations in WordPress plugins use OAuth. OAuth works by asking a user to log in through a browser, grant permission, and generate an access token. The plugin then uses that token to talk to Google’s API on the user’s behalf.
The problem is that OAuth tokens are not permanent. Google’s access tokens expire after one hour; refresh tokens last longer but can also be invalidated — when you change your Google account password, revoke third-party app access, or go longer than six months without the token being refreshed. When this happens, the plugin loses access to your calendar silently. Your booking widget may continue to show time slots — but it is working from stale cached data, not your live calendar. Double-bookings become possible.
A service account works differently. Instead of user credentials, it uses a JSON key file — a private key you download once from Google Cloud Console. The plugin uses that key to authenticate directly with Google’s API as a server-to-server call. There is no login flow, no token to refresh, and no expiry. Once configured, the integration works indefinitely unless you deliberately revoke or rotate the key.
For a booking plugin running on a live website, this distinction matters: the service account approach has no failure mode caused by credential expiry. Either it works or it returns an explicit error — it does not silently show stale data.
What you will need
- A Google account — any Gmail or Google Workspace account works
- Access to Google Cloud Console — free at console.cloud.google.com
- CalNative Booking installed on your WordPress site
- About 15–20 minutes
No billing setup is required. The Google Calendar API is free within its standard usage limits, which are far higher than any booking plugin will reach in normal use.
Step 1: Go to Google Cloud Console
Open your browser and go to console.cloud.google.com. Sign in with your Google account if prompted.
If this is your first time using Google Cloud Console, you may be asked to agree to terms of service. Accept them to continue. You do not need to set up billing for the Google Calendar API.
Step 2: Create a new project
A Google Cloud project is the container that holds your APIs and credentials. You need one project per application.
- At the top of the page, click the project selector dropdown (it shows the current project name or “Select a project”)
- In the popup, click New Project in the top right corner
- Enter a project name — something like
wordpress-booking - Leave the organisation field as-is and click Create
The project takes a few seconds to create. Once ready, make sure it is selected in the project selector before continuing — all steps below must be done inside this project.
Step 3: Enable the Google Calendar API
New projects start with no APIs enabled. You need to explicitly turn on the Calendar API.
- In the left navigation, go to APIs & Services → Library
- In the search box, type Google Calendar API
- Click the Google Calendar API result
- Click Enable
The page will refresh and show the API dashboard with a confirmation that it is now enabled. You can ignore the “Create Credentials” prompt — you will do that in the next step.
Step 4: Create a service account
- Go to APIs & Services → Credentials
- Click + Create Credentials at the top of the page
- Choose Service account from the dropdown
You will see a three-step form:
Step 1 — Service account details:
- Enter a Service account name — for example
booking-plugin. Google will generate the account ID automatically. - Optionally add a description — for example “Used by the WordPress booking plugin to read and write Google Calendar events”
- Click Create and Continue
Step 2 — Grant this service account access to the project: skip this step — click Continue.
Step 3 — Grant users access to this service account: skip this step too — click Done.
The service account is now created. On the Credentials page it appears under Service Accounts. Copy the service account email address — it looks like booking-plugin@your-project-id.iam.gserviceaccount.com. You will need it in Step 6.
Step 5: Create and download the JSON key
The JSON key file is what your WordPress plugin uses to authenticate as the service account. You download it once — Google does not allow you to download it again later.
- On the Credentials page, click the email address of the service account you just created
- Go to the Keys tab
- Click Add Key → Create new key
- Select JSON as the key type and click Create
A .json file downloads immediately. Treat this file like a password: do not share it publicly, do not commit it to a Git repository, and do not upload it to a publicly accessible folder on your server. The plugin uploads it to a protected location outside your webroot.
If you lose the file before uploading it, you cannot retrieve it from Google. Go back to the Keys tab, delete the existing key, and create a new one.
Step 6: Share your Google Calendar with the service account
The service account exists, but it has no access to your calendar yet. You need to share the calendar with it explicitly — the same way you would share a calendar with a colleague.
- Open Google Calendar at calendar.google.com
- In the left sidebar, find the calendar you want to use for bookings
- Click the three-dot menu (⋮) next to the calendar name and choose Settings and sharing
- Scroll to Share with specific people or groups and click Add people and groups
- Paste the service account email address from Step 4
- Set the permission to Make changes to events
- Click Send
“Make changes to events” is required — not just “See all event details”. The plugin needs to both read free/busy data (to determine available slots) and write new calendar events (when a booking is confirmed). Read-only access is not sufficient.
Step 7: Find your Calendar ID
While you are still in the calendar’s settings page from Step 6, scroll down to the Integrate calendar section and copy the Calendar ID.
For your primary Google Calendar, the Calendar ID is your Gmail address — for example yourname@gmail.com. For calendars you have created yourself, it is a longer string ending in @group.calendar.google.com.
Step 8: Upload to your WordPress plugin
In your WordPress admin, go to Settings → CalNative Booking. Paste your Calendar ID into the Calendar ID field and upload the JSON key file. Save your settings.
The plugin will begin reading your calendar immediately. Open your booking page — you should see available slots based on your working hours and current calendar events. If no slots appear, work through the troubleshooting section below.
Using a dedicated booking calendar (recommended)
You do not have to use your primary Google Calendar for bookings. Creating a separate calendar specifically for booking sessions has practical advantages:
- Cleaner separation — booking confirmations appear in their own colour in Google Calendar, distinct from personal and project events
- Easier revocation — if you ever want to stop using the plugin, you can unshare the booking calendar from the service account in one step, without touching your primary calendar’s sharing settings
- Multiple calendar support — you can share your primary calendar with the service account as well (read-only is sufficient for blocking), while using the dedicated calendar for confirmed booking events
To create a new calendar: in Google Calendar, click the + next to “Other calendars” in the left sidebar and choose Create new calendar. Give it a name like “Bookings” and save. Then share it with the service account email (Step 6) and use its Calendar ID (Step 7) in your plugin settings.
What the service account can and cannot access
A service account can only access what you explicitly share with it. It is not a master key to your Google account.
- It can read free/busy data and event details for calendars you have shared with it
- It can create, edit, and delete events on those calendars
- It cannot access your Gmail, Google Drive, Google Contacts, or any other Google service
- It cannot access calendars you have not explicitly shared with it — including other calendars in your Google account
If you share only a dedicated booking calendar (rather than your primary calendar) with the service account, its access is even more narrowly scoped — it can only read and write to that one calendar.
Troubleshooting common issues
The booking widget shows no available slots. Check that the Calendar ID in the plugin settings matches the calendar you shared with the service account. Also confirm the Google Calendar API is enabled in the correct project (Step 3) — it is easy to enable it in the wrong project if you have multiple.
An existing calendar event is not blocking a slot. The event must be on the calendar whose ID you entered in the plugin. Events on other calendars in your Google account are not checked. Move the event to the booking calendar, or create a blocking event there manually.
The plugin says the JSON key is invalid. Upload the file exactly as downloaded — do not open, edit, or rename it. If you accidentally modified it, delete the key from Google Cloud Console (Credentials → Keys tab → Delete) and create a new one from scratch.
You see a permission error after saving settings. The service account was shared with the calendar but with insufficient permissions. Return to the calendar’s sharing settings (Step 6), find the service account email address, and change the permission level to Make changes to events.
You shared the calendar but slots still do not appear. Calendar sharing sometimes takes a minute or two to propagate through Google’s systems. Wait two minutes and reload your booking page before investigating further.
The project selector shows “No organisation” and you cannot proceed. This is normal for personal Gmail accounts. Leave the organisation field blank and continue — organisation is only required for Google Workspace accounts managed by a company.
How long does the setup last?
Service account credentials do not expire. Once you complete this setup, it works indefinitely. You do not need to reconnect, refresh tokens, or revisit Google Cloud Console unless you deliberately rotate or revoke the key.
If you ever want to rotate the key for security reasons — for example, if you believe the JSON file may have been exposed — go to the Keys tab of your service account in Google Cloud Console, create a new key, download it, and upload it to the plugin settings. Then delete the old key. The new key takes effect immediately.
