Quickstart With Calendar Sync

Use this setup when each signed-in user should connect Google Calendar. Your backend creates the frontend session, while your browser starts Google authorization and enables the calendars returned by the connected account.

Google Calendar Sync requires the GoogleCalendarSync entitlement.

1. Get An Organization API Token

Email tom@schedule-x.dev and ask for a Schedule-X Cloud organization API token with Google Calendar Sync enabled.

SCHEDULE_X_ORGANIZATION_ID=<organization-id>
SCHEDULE_X_ORG_API_TOKEN=sx_org_...

Keep the organization API token on your backend. Google and organization credentials must never be exposed in browser code, logs, analytics events, or public repositories.

2. Install

npm install @schedule-x-cloud/sdk temporal-polyfill @schedule-x/calendar @schedule-x/calendar-controls @schedule-x/event-recurrence @schedule-x/theme-default @schedule-x/translations @sx-premium/interactive-event-modal @sx-premium/sidebar

3. Add The Backend Token Endpoint

Create the server client in trusted backend code:

import { ScheduleXServerClient } from '@schedule-x-cloud/sdk/server'

const scheduleX = new ScheduleXServerClient({
  apiKey: process.env.SCHEDULE_X_ORG_API_TOKEN!,
  organizationId: process.env.SCHEDULE_X_ORGANIZATION_ID!,
})

app.post('/api/schedule-x/token', requireUser, async (req, res) => {
  res.json(await scheduleX.auth.createFrontendSession({
    externalUserId: req.user.id,
    email: req.user.email,
    displayName: req.user.name,
  }))
})

externalUserId must be the stable ID from your authenticated application user. Schedule-X Cloud creates or updates its internal user and returns a fresh one-hour frontend token; you do not need to store the Cloud user ID.

4. Create The Browser Clients

Use one token function for the Google integration calls and the rendered calendar:

import 'temporal-polyfill/global'
import '@schedule-x/theme-default/dist/index.css'
import '@sx-premium/interactive-event-modal/index.css'
import '@sx-premium/sidebar/index.css'
import {
  ScheduleXBrowserClient,
  createScheduleXCloudCalendar,
} from '@schedule-x-cloud/sdk'

const getFrontendToken = async () => {
  const response = await fetch('/api/schedule-x/token', { method: 'POST' })
  return (await response.json()).token
}

const cloud = new ScheduleXBrowserClient({ token: getFrontendToken })

5. Connect Google Calendar

In the Cloud console, select the environment and add your application’s exact origin under Settings → OAuth return origins. For local development this may be http://localhost:3000; deployed applications must use HTTPS.

Start authorization from an explicit action by the signed-in user:

async function connectGoogleCalendar() {
  const returnUrl = `${window.location.origin}${window.location.pathname}`
  const { url } = await cloud.integrations.googleCalendar.getConnectUrl({
    returnUrl,
  })

  window.location.assign(url)
}

Google redirects through Schedule-X Cloud and back to the registered origin in returnUrl with a googleCalendar query parameter. Unregistered origins are rejected before authorization starts. After a successful connection, render the calendar with provider synchronization enabled:

const result = new URL(window.location.href).searchParams.get('googleCalendar')

if (result && result !== 'success') {
  throw new Error(`Google Calendar connection returned ${result}.`)
}

For a calendar picker instead of enabling everything, use the selective flow in Google Calendar Sync.

6. Render The Synchronized Calendar

const calendarApp = createScheduleXCloudCalendar({
  getFrontendToken,
  initialProviderSync: true,
})
calendarApp.render(document.getElementById('calendar')!)

The calendar shows its built-in loading state, enables the user’s visible Google calendars, and displays partial data while initial imports are still running. A timed-out import remains in the partial state and is polled until it succeeds or fails. A failed provider calendar is reported without blocking the calendars that did load.

The same calendar loads each visible event range, persists permitted changes, and refreshes automatically when Google webhooks deliver event or calendar metadata changes. It also requests a fresh frontend token after a 401 before retrying once.

Pass the same calendarApp to the existing React, Vue, Angular, or Svelte Schedule-X component instead of calling render() yourself.