# Google sign-in and Calendar

> Create Google OAuth credentials for "Continue with Google" and, in the Scheduler, Google Calendar sync.

Google is optional. Without it, people sign in with email and password, and the Scheduler checks for conflicts using CalDAV and ICS calendars only.

With a Google OAuth client, the apps can offer:

- **Continue with Google** on the sign-in page (both apps).
- **Connect Google Calendar** in the Scheduler, so bookings check your Google Calendar for conflicts and new bookings are added to it.

Both come from the same two variables:

```sh
GOOGLE_CLIENT_ID=1234567890-abc123.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
```

OAuth is the standard way for an app to ask Google for permission on a user's behalf. You register your app with Google once, in a Google Cloud project, and get a **client ID** (public) and a **client secret** (private). It's free.

Setup takes about 15 minutes. Google sign-in alone is quick. Google Calendar has two more steps that are easy to miss: enabling the Calendar API, and publishing the app so access doesn't expire after 7 days.

## Before you start

- A Google account. If you use Google Workspace and only people in your organization will use the app, use that Workspace account (see [Internal apps](#internal-apps-for-google-workspace)).
- Your app's final HTTPS address, for example `https://cal.example.com`. Google only accepts `https://` addresses (or `http://localhost` for testing), so set up your domain first. If you change the address later, you must update the client.

## What the app asks Google for

| Feature | Scopes (permissions) | Google review needed? |
|---------|----------------------|-----------------------|
| Sign-in (both apps) | `openid`, `email`, `profile`: name, email address and profile photo | No |
| Calendar (Scheduler) | `https://www.googleapis.com/auth/calendar.events` (view and edit events on your calendars) and `https://www.googleapis.com/auth/calendar.freebusy` (view your availability) | Sensitive scopes: unverified apps show a warning (see below) |

The Scheduler asks for calendar access separately, only when a user clicks **Connect Google Calendar**, so signing in with Google never asks for calendar access.

## Redirect URIs

A redirect URI is the address Google sends the user back to after they approve access. Google only redirects to addresses you have listed in advance, exactly as written. Replace `https://cal.example.com` with your `APP_URL`:

| App | Redirect URIs |
|-----|---------------|
| Scheduler | `https://cal.example.com/api/auth/callback/google` (sign-in) and `https://cal.example.com/api/calendars/google/callback` (Calendar) |
| Invoicing | `https://billing.example.com/api/auth/callback/google` |

## Step 1: Create or pick a project

1. Open the [Google Cloud Console](https://console.cloud.google.com/).
2. Use the project picker at the top to create a new project (for example "Scheduler") or select an existing one.

## Step 2: Enable the Google Calendar API (Scheduler only)

Skip this step for sign-in only.

1. Open the [Google Calendar API enable page](https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com) with your project selected.
2. Confirm to enable the API.

Without this, connecting a calendar seems to work but every calendar request fails.

## Step 3: Configure the Google Auth Platform

The OAuth settings live in the Google Auth Platform section of the console (it replaced the old "OAuth consent screen" page), which has the pages **Branding**, **Audience**, **Clients** and **Data access**.

1. Go to the menu, then **Google Auth platform > Branding**.
2. If you see "Google Auth platform not configured yet", click **Get Started**.
3. Under **App Information**, enter an **App name** (users see it on Google's consent screen, for example "Acme Scheduling") and choose a **User support email**. Click **Next**.
4. Under **Audience**, choose **External** (anyone with a Google account), or **Internal** if you're on Google Workspace and only your organization will use the app. Click **Next**.
5. Under **Contact Information**, enter an email address where Google can reach you. Click **Next**.
6. Under **Finish**, select **I agree to the Google API Services: User Data Policy**, then click **Continue** and **Create**.

## Step 4: Create the OAuth client

1. Go to **Google Auth platform > Clients** and click **Create client**.
2. For **Application type**, choose **Web application**, and give it a name (for example "Scheduler production").
3. Under **Authorized redirect URIs**, click to add a URI and enter each redirect URI from the [table above](#redirect-uris) for your app. You don't need **Authorized JavaScript origins**.
4. Click **Create**.
5. Copy the **Client ID** and **Client secret** right away, or download the JSON file. Google shows the full secret only once. If you lose it, add a new secret to the client and delete the old one.

## Step 5: Add the calendar scopes (Scheduler only)

1. Go to **Google Auth platform > Data access**.
2. Click **Add or Remove Scopes**.
3. Add `https://www.googleapis.com/auth/calendar.events` and `https://www.googleapis.com/auth/calendar.freebusy`. If they aren't in the list, paste them into the field for adding scopes manually.
4. Click **Update** if asked, then **Save**.

The basic sign-in scopes don't need to be added here.

## Step 6: Publish the app

This step matters for the Scheduler. A new External app starts in **Testing** status, and in Testing:

- only test users you list on the **Audience** page (up to 100) can grant calendar access, and
- **their calendar access expires after 7 days**. Google withdraws the permission, and the Scheduler stops seeing their calendar until they reconnect.

Sign-in with only the basic scopes isn't affected: it works for everyone and doesn't expire, even in Testing. So Invoicing can stay in Testing.

To publish:

1. Go to **Google Auth platform > Audience**.
2. Under **Publishing status**, click **Publish app** and confirm.

The status changes to **In production**. You don't need to submit for verification to publish.

### The unverified app warning and the 100-user cap

Because the calendar scopes are sensitive, users who connect Google Calendar to an app Google hasn't verified see a "Google hasn't verified this app" screen. They can continue through the screen's advanced option. For a self-hosted app used by you and your team, that's normal: you're the developer and the user.

An unverified app can be authorized by at most 100 new users over the life of the Google Cloud project. To remove the warning and the cap, submit the app for verification from the Google Auth Platform pages. Google reviews sensitive scopes and asks why you need each one; expect to provide a homepage, a privacy policy, and details on how the app uses calendar data. Most self-hosters don't need this.

### Internal apps for Google Workspace

If your Google Cloud project belongs to a Google Workspace organization, you can choose **Internal** as the audience. Only accounts in your organization can then sign in or connect calendars, there's no publishing step, no 7-day expiry, and no unverified-app warning. People outside your organization see an `org_internal` error, so don't use Internal if outside guests need to sign in. (Guests who only book times don't need Google at all.)

## Step 7: Configure the app

Set the two variables on your deployment and restart or redeploy:

```sh
GOOGLE_CLIENT_ID=1234567890-abc123.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
```

Both must be set; with only one, Google stays off. Check that it's on:

```sh
curl -fsS https://cal.example.com/api/bootstrap
# ... "features":{"google":true, ...
```

## Step 8: Test it

1. Sign out and open the sign-in page. Click **Continue with Google**. If your account doesn't exist yet in the app, Google sign-in only works for an address with a pending invite (or with `ALLOW_SIGNUP=true`). See [first admin](./first-admin.md).
2. In the Scheduler, go to **Calendars** and click **Connect Google Calendar**. Approve access. You're sent back with the message "Google Calendar connected", and your primary Google calendar is used for conflict checks.

## Troubleshooting

- **`Error 400: redirect_uri_mismatch`** from Google: the redirect URI isn't listed on the client exactly as the app sends it. Compare it character by character with `APP_URL` (scheme, host, no trailing slash) plus the path from the [table](#redirect-uris). Changes to the client can take from 5 minutes to a few hours to apply.
- **"Continue with Google" doesn't appear:** one of the two variables is missing on the running app, or the app wasn't restarted.
- **"Sign-up is invite-only on this server"** after choosing a Google account: that email has no account and no pending invite. Invite it first.
- **"Google connection failed. Try again."** after connecting a calendar: you declined access, or Google didn't return a long-lived token. Remove the app's access from your Google account's third-party connections at [myaccount.google.com/connections](https://myaccount.google.com/connections), then connect again.
- **Busy times from Google stop showing up after about a week:** the app is still in Testing. Publish it (step 6), then each user reconnects Google Calendar.
- **`Error 403: access_denied`** mentioning that the app is in testing: publish the app or add the user as a test user on the **Audience** page.
- **Calendar requests fail with an error about the API being disabled:** enable the Google Calendar API (step 2) in the same project as the client.
- **You changed `AUTH_SECRET`:** saved calendar connections are encrypted with it and can't be read anymore. Each user must remove and reconnect their calendars.

## Adding this to an existing deploy

You can add Google at any time. Do steps 1 to 6 above in the Google Cloud Console (steps 2 and 5 only for Google Calendar in the Scheduler), then set these variables on the running app:

```sh
GOOGLE_CLIENT_ID=1234567890-abc123.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
```

- **Railway:** open the app service's **Variables** tab, add the variables, and deploy the staged changes. Railway redeploys the service.
- **Render:** open the web service's environment settings, add the variables, and save. Render redeploys the service.
- **Docker Compose:** add the variables to `.env` in the app's folder (`apps/scheduler` or `apps/invoicing`), then run `docker compose up -d` in that folder. This recreates the app container with the new values. `docker compose restart` is not enough, because it doesn't reload `.env`.

The new settings take effect only after this restart or redeploy.

To confirm it works:

1. `curl -fsS https://<your address>/api/bootstrap` shows `"google":true`.
2. The sign-in page shows **Continue with Google**, and signing in with an existing user's Google address works.
3. In the Scheduler, **Calendars > Connect Google Calendar** ends with "Google Calendar connected".

Existing accounts keep their passwords. If you later change `APP_URL`, add the new redirect URIs to the Google client.