Calendar Sync Token
Data Entity
Description
Stores OAuth tokens and sync configuration for peer mentor calendar integrations, enabling Meander activities to be synchronized with external calendar providers (Google Calendar, Apple Calendar, etc.). One token record per user, containing access/refresh tokens and provider metadata.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
user_id |
uuid |
Foreign key to users table — one sync token record per user | requiredunique |
provider |
enum |
Calendar provider the token was issued by | required |
access_token |
text |
Encrypted OAuth2 access token for the calendar provider API | required |
refresh_token |
text |
Encrypted OAuth2 refresh token used to obtain new access tokens without re-authorization | - |
token_expires_at |
datetime |
UTC timestamp when the access token expires; triggers automatic refresh before this time | required |
scope |
text |
OAuth scopes granted by the user, space-separated (e.g. 'calendar.events.write calendar.readonly') | - |
calendar_id |
string |
Provider-specific calendar identifier to sync events into (e.g. Google Calendar ID or Apple calendar UUID) | - |
sync_enabled |
boolean |
Whether the user has enabled calendar sync; toggled from CalendarSyncSettingsScreen | required |
sync_direction |
enum |
Direction of sync: push activities to calendar, or bidirectional | required |
last_synced_at |
datetime |
UTC timestamp of the most recent successful sync operation | - |
sync_cursor |
string |
Provider-specific incremental sync cursor or page token to enable delta syncs instead of full re-syncs | - |
created_at |
datetime |
UTC timestamp when the token record was first created (initial OAuth authorization) | required |
updated_at |
datetime |
UTC timestamp of the last token update (refresh, settings change) | required |
revoked_at |
datetime |
UTC timestamp when the user revoked calendar access; null if still authorized | - |
Database Indexes
idx_calendar_sync_tokens_user_id
Columns: user_id
idx_calendar_sync_tokens_token_expires_at
Columns: token_expires_at
idx_calendar_sync_tokens_sync_enabled
Columns: sync_enabled
Validation Rules
token_expires_at_in_future_on_create
error
Validation failed
provider_must_be_known_value
error
Validation failed
access_token_required
error
Validation failed
scope_present_for_write_sync
error
Validation failed
user_id_references_active_user
error
Validation failed
Business Rules
one_token_per_user
A user may have at most one active calendar sync token record. A second OAuth authorization replaces the existing record (upsert on user_id).
auto_refresh_before_expiry
CalendarSyncService must refresh the access token at least 5 minutes before token_expires_at. If refresh fails, sync_enabled is set to false and the user is notified.
revoked_token_disables_sync
When revoked_at is set, sync_enabled must be false. Any sync attempt on a revoked record must be rejected immediately without calling the provider API.
sync_requires_module_toggle
Calendar sync is part of the activity-registration module. The token may only be created or used when the organization's activity-registration module is enabled.
tokens_encrypted_at_rest
access_token and refresh_token must be encrypted before persistence using the platform's field-level encryption key. Plain-text tokens must never reach the database layer.