← All documentation

Connect Gmail and Google Calendar.

InventDB reaches Gmail and Google Calendar through a Google credential you create yourself and can revoke at any time. This guide builds it in the Google Cloud Console: a project, the two APIs switched on, a consent screen, and a web OAuth client whose ID and secret you paste into the engine. Everything happens in the browser.

A personal @gmail.com account works. A work account on Google Workspace also works, but an administrator may have restricted who can create projects; if a step is blocked later, that is why.

Check the account before every click. If you use several Google accounts, look at the profile picture in the top right corner of each Console page. Building the project under the wrong account is the most common mistake, and it stays invisible until sign-in fails much later. Nothing here is destructive; you can delete the project at the end and start over.

Google grants access only when three things line up, and the next sections build them in order:

Why your own project: the engine ships no shared Google credential. Your mailbox and calendar are reached through a credential only you control, and revoking it never affects anyone else.

On cost: neither API needs a billing account. If any screen asks for a payment method, you have wandered into a different Google product; go back rather than entering card details.

Project picker ▸ New project

The project picker is the dropdown in the bar at the top of the page, to the right of the Google Cloud logo. On a new account it reads Select a project.

1. Click the project picker, then New project at the top right of the dialog that opens.
2. In Project name, type something you will recognise in six months; Gmail Calendar Tool is fine. Names can be changed later.
3. Check the Project ID shown underneath. Google generates it from the name plus digits, and it can never be changed after creation. Click Edit now if you want a tidier one.
4. Leave Location as No organisation on a personal account. On a work account, pick the organisation or folder your administrator told you to use.
5. Click Create. Creation takes ten to twenty seconds; a notification lands in the bell icon at the top right.

Google does not always switch you into the new project. Look at the project picker again; it must show the project you just made. If it shows something else, click it and select yours. Every remaining step applies to whichever project is named up there.

Enable the two APIs

Navigation menu ▸ APIs & Services ▸ Library

The navigation menu is the three-line icon at the far top left. If APIs & Services is not in it, search for API Library in the top bar instead. You enable each API separately:

1. In the Library, search Gmail API and open the result titled exactly Gmail API, published by Google Enterprise API. Similarly named third-party listings exist.
2. Click Enable. When the page turns into a management screen with Metrics and Quotas tabs, it worked.
3. Return to the Library, search Google Calendar API, open it and click Enable again.

If a button reads Manage instead of Enable, that API is already on for this project; move on.

Checkpoint: under APIs & Services ▸ Enabled APIs & services, both Gmail API and Google Calendar API are listed. Google switches on some housekeeping APIs by default, so a list longer than two entries is normal.

APIs & Services ▸ OAuth consent screen

Google reorganised this area recently, so the link may land on a section called Google Auth Platform with pages named Branding, Audience, Clients and Data access. The information asked for is the same either way. On a new project a Get started panel appears; work through it:

1. App name. Shown to whoever signs in, in the sentence "wants access to your Google Account". Use something plain like Gmail Calendar Tool, and do not put the word Google in it; Google rejects app names containing its trademarks.
2. User support email. Pick your own address from the dropdown.
3. Audience. Choose External on a personal account; it is the only option you have. Internal appears only on Google Workspace accounts, restricts the app to your organisation, and skips the test user step below.
4. Contact information. Your email address again; Google uses it to notify you about the project.
5. Agree to the Google API Services: User Data Policy and click Create.

The optional fields, app logo, home page and privacy policy link, can stay empty for a personal tool. They become mandatory only if you later submit the app for verification so that strangers can use it.

Checkpoint: the Audience page shows Publishing status: Testing. That is expected and correct for now.

Add yourself as a test user

While the status is Testing, Google refuses to sign in any account that is not on an explicit list, including the account that owns the project. Skipping this produces an access_denied error later that is very hard to trace back here, so do it now.

OAuth consent screen ▸ Audience ▸ Test users

1. Click Add users.
2. Type the full Gmail address of every account that will connect, starting with your own, one per line.
3. Click Save.

Worth knowing now: in Testing, a stored sign-in expires after seven days and the engine asks you to reconnect. That is Google's rule rather than a fault in the engine, and it stops once the app is published to Production, a separate process you can do later if you need it.

Data access, or scopes

Scopes are the individual permissions the engine will ask for, and it names them itself when you connect. While the app is in Testing you can leave the Data access page empty and the consent screen still works; declaring scopes matters when you publish. To declare them, open Data access, click Add or remove scopes, filter for gmail or calendar, tick the ones needed, then Update and Save.

If you do declare scopes, take the narrowest that do the job: reading mail is gmail.readonly, sending is gmail.send, reading and writing events is calendar.events. The broad scopes, https://mail.google.com/ and calendar, grant far more than the engine needs and make Google's verification review stricter if you ever publish.

Get the redirect URI first. Mid-form, Google asks where to send people back after sign-in, and the address must match what the engine expects character for character. Open the engine's Google connection page in a second browser tab now and copy the redirect URI it displays. Keep that tab open; the next section returns to it. Do not type the address from memory.

APIs & Services ▸ Credentials ▸ + Create credentials ▸ OAuth client ID

In the newer layout the same form lives at Google Auth Platform ▸ Clients ▸ Create client.

1. Application type: select Web application. The engine runs on a server and the sign-in ends at a public address. Desktop app is for scripts on your own machine and produces a redirect_uri_mismatch you cannot fix without starting over; a service account is a different mechanism entirely and cannot read a personal Gmail inbox.
2. Name: visible only to you in the Console. InventDB engine works.
3. Authorized JavaScript origins ▸ Add URI: your workspace's base address, scheme and host only, no path, no trailing slash: https://<your-workspace>.inventdb.com.
4. Authorized redirect URIs ▸ Add URI: the full redirect URI you copied from the engine. This one does include a path. Trailing slashes matter, http and https are different entries, and so is a different subdomain.
5. Click Create. A dialog shows the Client ID and Client secret.

The secret is shown once. Copy both values or click Download JSON before closing the dialog; Google never shows the secret again. If you lose it, open the client and use Reset secret, which invalidates the old value and breaks anything still using it. Treat the secret like a password: never in Git, a chat, a ticket or a screenshot. If it leaks, reset it immediately.

Checkpoint: a client of type Web application is listed under OAuth 2.0 Client IDs, and you hold an ID ending in .apps.googleusercontent.com and a secret beginning GOCSPX-.

<your-workspace>.inventdb.com/engine ▸ Google connection

1. Paste the Client ID and Client secret into their fields. Check for a stray space at either end; copying from the Google dialog sometimes picks one up, and it produces an invalid_client error that looks like a wrong secret.
2. Save, then click Connect. The engine sends you to Google.
3. Work through the Google screens; the next section describes them.
4. Google returns you to the engine, which now shows the connection as active.

If Google shows redirect_uri_mismatch instead of a sign-in: the registered URI does not exactly match what the engine sent. The error page prints the address Google actually received; copy that string into Authorized redirect URIs and save. Client changes can take a few minutes to propagate, so give a corrected URI five minutes before assuming it is still wrong.

If your workspace address ever changes: the old redirect URI stops matching and every connection fails until the new address is registered in the Cloud Console. Add the new URI alongside the old one rather than replacing it while both addresses are in use.

The "Google hasn't verified this app" warning

An interstitial appears with a Back to safety button. This is what every unverified app looks like, and yours is unverified because you never submitted it for review. Click Advanced at the bottom left, then Go to [your app name] (unsafe). The word unsafe describes unverified apps in general and not yours in particular; you built it and know what it does.

The permissions list

Google then lists what the engine is asking for, each item with a checkbox. Tick every box. An unticked permission is silently refused, and the failure surfaces much later as a confusing error rather than a clear one. Click Continue and the browser returns to the engine with the connection active. Your sign-in is stored on the server, so you are not asked again until it expires.

Gmail and Calendar share one grant

Google keeps one grant per app and account rather than one per API. Mail and calendar permissions arrive on the same consent screen, and the engine reaches both services through the single grant that consent creates. A newer consent replaces the older grant, which is why the engine asks for everything already granted each time you reconnect: approving the full list keeps both services on the one live grant.

So whenever the consent screen reappears, keep every box ticked. Unticking a permission at a later consent removes it from the grant both services depend on, and the service you connected first stops working even though its settings look untouched. After the seven-day Testing expiry, one reconnect with the full list approved brings Gmail and Calendar back together.

Wrong Google account?

Disconnect in the engine, click Connect again and pick the right account in the chooser. If Google skips the chooser, sign out of the unwanted account in that browser first, or use a private window.

Revoking later

Whatever you granted can be withdrawn at any time from your Google account under Security ▸ Your connections to third-party apps. Removing the app there cuts the engine off immediately, and because of the shared grant it cuts off Gmail and Calendar at once, whatever the engine's own settings say.

That is the whole setup: a project with both APIs on, a consent screen in Testing with your account as a test user, a web client pointing at the engine, and a live connection. The credential grants access to your own mailbox and calendar only, so it is not something to hand to a colleague; send them this guide instead.

All documentation