# Google Calendar

Connect Google Calendar and use its tools through the Authlane control plane.

## Prerequisites

Create a Google OAuth client for a project with Calendar access. The connected Google account must
be able to see each calendar that your SaaS will read or change. Use the
[Calendar API guide](https://developers.google.com/workspace/calendar/api/guides/overview),
[OAuth consent guide](https://developers.google.com/workspace/guides/configure-oauth-consent), and
[Google Cloud credentials console](https://console.cloud.google.com/apis/credentials).

## Self-hosted setup

1. Create or select a Google Cloud project and enable Calendar API. For MCP-first execution, also
   join the Workspace Developer Preview and enable Calendar MCP API.
2. Configure the OAuth consent screen, audience, test users, and the scopes below.
3. Create a **Web application** OAuth client and add
   `https://<your-authlane-host>/api/v1/oauth/google-calendar/callback` as an authorized redirect.
4. Copy the Client ID and Client Secret.

## Configure authentication

Open **Dashboard → Services → Google Calendar → OAuth Configuration**, enter the Client ID and
Client Secret, save, and enable the service. The registered callback must match the public Authlane
URL exactly.

## Scopes

**Read-only tools** requests `calendar.readonly` and `calendar.events.readonly`. **Full tool set**
uses the write-capable event scope below. Authlane filters the corresponding definitions in
addition to requesting least-privilege OAuth scopes.

- `https://www.googleapis.com/auth/calendar.events` permits event creation, updates, and deletion.
- `https://www.googleapis.com/auth/calendar.readonly` permits calendar and event reads.

## Execution path

Prefer Google's official Calendar MCP server at `https://calendarmcp.googleapis.com/mcp/v1`; follow
the [official Calendar MCP guide](https://developers.google.com/workspace/calendar/api/guides/configure-mcp-server).
Because it is a Developer Preview, use the direct Calendar API adapter as the explicit fallback for
missing tools or deployments that cannot enable the preview.

## Available tools

### Calendars and events

- `gcal_list_calendars`
- `gcal_list_events`
- `gcal_get_event`

### Create and change events

- `gcal_create_event`
- `gcal_quick_add`
- `gcal_update_event`
- `gcal_delete_event`

Install `@authlane/integration-google-calendar` in the SaaS runtime. A local callback requests a
fresh credential lease and calls Google Calendar directly; Authlane does not proxy event inputs or
provider responses.

## Connection lifecycle

After consent, Authlane stores the Google OAuth credential encrypted and reports `connected`.
Authlane refreshes it before expiry when Google returned refresh material. If refresh fails
permanently, show reconnect for the resulting `expired` or `error` state. Hosted disconnect uses a
fresh session with recent reauthentication and removes the connection.

## Troubleshooting

- Use `primary` or a calendar ID returned by `gcal_list_calendars`; a display name is not a stable
  calendar ID.
- Event start and end values must use the date or RFC 3339 formats described by the tool schema.
- A calendar can be visible but not writable; event mutations still require calendar permission
  plus `https://www.googleapis.com/auth/calendar.events`.