Google sign-in and Calendar
Create Google OAuth credentials for "Continue with Google" and, in the Scheduler, Google Calendar sync.
View as MarkdownCoding agents can read this page at /docs/google-oauth.md
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:
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).
- Your app’s final HTTPS address, for example
https://cal.example.com. Google only acceptshttps://addresses (orhttp://localhostfor 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
- Open the Google Cloud Console.
- 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.
- Open the Google Calendar API enable page with your project selected.
- 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.
- Go to the menu, then Google Auth platform > Branding.
- If you see “Google Auth platform not configured yet”, click Get Started.
- 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.
- 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.
- Under Contact Information, enter an email address where Google can reach you. Click Next.
- Under Finish, select I agree to the Google API Services: User Data Policy, then click Continue and Create.
Step 4: Create the OAuth client
- Go to Google Auth platform > Clients and click Create client.
- For Application type, choose Web application, and give it a name (for example “Scheduler production”).
- Under Authorized redirect URIs, click to add a URI and enter each redirect URI from the table above for your app. You don’t need Authorized JavaScript origins.
- Click Create.
- 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)
- Go to Google Auth platform > Data access.
- Click Add or Remove Scopes.
- Add
https://www.googleapis.com/auth/calendar.eventsandhttps://www.googleapis.com/auth/calendar.freebusy. If they aren’t in the list, paste them into the field for adding scopes manually. - 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:
- Go to Google Auth platform > Audience.
- 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:
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:
curl -fsS https://cal.example.com/api/bootstrap
# ... "features":{"google":true, ...
Step 8: Test it
- 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. - 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_mismatchfrom Google: the redirect URI isn’t listed on the client exactly as the app sends it. Compare it character by character withAPP_URL(scheme, host, no trailing slash) plus the path from the table. 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, 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_deniedmentioning 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:
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
.envin the app’s folder (apps/schedulerorapps/invoicing), then rundocker compose up -din that folder. This recreates the app container with the new values.docker compose restartis not enough, because it doesn’t reload.env.
The new settings take effect only after this restart or redeploy.
To confirm it works:
curl -fsS https://<your address>/api/bootstrapshows"google":true.- The sign-in page shows Continue with Google, and signing in with an existing user’s Google address works.
- 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.