Connections

Calendar provider OAuth links. Google, Microsoft and iCloud — one API, three providers.

Endpoints

POST /v1/connections/start Start a connection OAuth flow

POST /v1/connections/callback Server-side callback (Connect)

GET /v1/connections List connections

GET /v1/connections/{id} Retrieve a connection

DELETE /v1/connections/{id} Disconnect

POST /v1/connections/{id}/refresh Force a fresh sync

Object shape

A connection represents a user's OAuth link to a single calendar provider. One user can have many connections (e.g. work Google + personal Microsoft).

Field	Type	Description
id	string	Prefixed con_.
object	string	Always connection.
provider	string	google, microsoft, or icloud (beta).
status	string	active, disconnected, error.
email	string	The provider account's email address.
sync_mode	string	realtime (webhook-driven) or polling (fallback).
last_synced_at	datetime	Most recent successful sync.
calendars	array	The provider's exposed calendars (see Calendars).
webhook_subscription	object?	Current webhook subscription state — id, expires_at.
token_refresh	object	last_at, failures_count — telemetry on the auth health.
created_at	datetime	Creation time.

Start a connection

HTTP
POST /v1/connections/start

Returns a redirect_url your application should send the user to. After consent, ChronaPilot calls your return_url with ?connection_id=con_…&state=….

Body field	Type	Description
provider	string	google, microsoft, or icloud.
user_id	string	Your ChronaPilot user ID.
return_url	string	Where to redirect after consent.
scopes	array?	Restrict requested scopes (default: full read+write).

List connections

HTTP
GET /v1/connections

Filter by user_id or provider.

Retrieve

HTTP
GET /v1/connections/{id}

expand[]=calendars includes the full per-calendar list inline.

Disconnect

HTTP
DELETE /v1/connections/{id}

Revokes tokens with the provider, tears down webhook subscriptions, and stops syncing. Events already mirrored remain in ChronaPilot but no longer push back to the provider.

Force resync

HTTP
POST /v1/connections/{id}/refresh

Triggers an immediate full sync from the provider. Used after manual edits or to recover from a sync_failed state. Rate-limited to 1 per minute per connection.

Reference implementation

CalendarConnection.cs — entity
GoogleCalendarService.cs — Google provider
MicrosoftCalendarService.cs — Microsoft Graph provider
WebhookSubscriptionService.cs — webhook lifecycle