Skip to content
Leverage AI Developer Support

Microsoft Calendar Connector

Use this page when you need the Microsoft-side setup details for the Microsoft Calendar connector. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

Section titled “Runtime Shape”
  • Implemented modes: fixed live
  • Auth binding: Better Auth generic OAuth provider id microsoft
  • Callback URI examples:
    • http://localhost:3001/api/auth/oauth2/callback/microsoft
    • https://auth.example.com/api/auth/oauth2/callback/microsoft
  • Setup console URL:
  • Required connector scopes:
    • Calendars.Read

Provider-Specific Gotchas

Section titled “Provider-Specific Gotchas”
  • Microsoft Calendar is a separate connector key: microsoft-calendar. Do not reuse, rename, or broaden the existing outlook mail connector.
  • The connector uses delegated Calendars.Read. Do not add Calendars.Read.Shared unless product explicitly accepts shared or delegated calendar coverage.
  • Calendar discovery uses Microsoft Graph /me/calendars.
  • Date-window and upcoming event lookup uses /me/calendar/calendarView and /me/calendars/{id}/calendarView, which require startDateTime and endDateTime.
  • Focused event search uses Microsoft Search API POST /v1.0/search/query with entityTypes: ["event"] where supported.
  • Microsoft Search event search is scoped to the signed-in user’s primary calendar, does not support delegated mailbox search, does not support event sorting, and has limited personal Microsoft account support.
  • Recent changed-event lookup is not enabled unless a provider path with update-time filtering is accepted; do not simulate it with broad text search.
  • Microsoft Calendar, Microsoft Contacts, Outlook, and OneDrive share the same connector auth binding. Reauthorization under an existing linked microsoft account requests the full scope set needed by sibling Microsoft connectors under that account.
  • Calendar grounding must preserve private/limited-detail source kinds and must not expose opaque provider ids in user-facing answer text unless the user explicitly asks for identifiers.

Canonical Sources

Section titled “Canonical Sources”
  • packages/domain/src/connectors/connectorRegistry.ts
  • apps/auth/src/genericOAuthProviders.ts
  • apps/api/src/mastra/tools/microsoftCalendarLiveQuery.ts
  • apps/api/src/connectors/liveAccessCalendarContracts.ts
  • docs/features/connectors/spec.md
  • docs/features/live-query/spec.md

Official Docs

Section titled “Official Docs”