Calendar API

This document describes the endpoints for integrating external calendars (Google, Outlook) with the user's workspace. All endpoints require authentication.

---

General Management

These endpoints allow you to check the status of integrations or remove them, regardless of the provider.

Get Connection Status (FUTURE)

Checks if the current user has an active calendar integration and validates if the required permissions (scopes) are still granted.

Endpoint: POST /api/v1/calendar/status

Request Body: None

Success Response: 200 OK

{
  "isConnected": true,
  "provider": "google",
  "email": "user@example.com",
  "scopesValid": true,
  "syncedAt": "2023-10-27T10:00:00Z"
}

Note: If isConnected is false, the other fields will be null or omitted.

---

Google Integration

Initiate Google Connection

Generates a Google OAuth authorization URL wrapped by WorkOS. The frontend should redirect the user to the returned redirectUrl to begin the consent flow.

Endpoint: POST /api/v1/calendar/google/connect

Request Body:

{
  "state": "random_string_xyz",
  "codeChallenge": "pkce_challenge_string"
}

Parameters:

• state (required): A random string generated by the client to prevent CSRF attacks.
• codeChallenge (required): The PKCE code challenge generated by the client.

Success Response: 200 OK

{
  "redirectUrl": "https://api.workos.com/oauth/authorize?response_type=code&client_id=...&provider=Google..."
}

Here are the two new sections to add under the Google Integration section of your documentation.

List Calendars

Retrieves the list of all calendars associated with the user's Google account (e.g., Primary, Birthdays, Shared Calendars).

Endpoint: POST /api/v1/calendar/google/calendars

Request Body:

Note: The refreshToken field is currently required for testing purposes. In the final production implementation, this token will be retrieved securely from the database based on the authenticated user and this route will be registered as a GET

{
  "refreshToken": "1//0g..."
}

Success Response: 200 OK

[
  {
    "id": "primary",
    "name": "john.doe@example.com",
    "color": "#123456"
  },
  {
    "id": "addressbook#contacts@group.v.calendar.google.com",
    "name": "Birthdays",
    "color": "#92e1c0"
  }
]

List Events

Retrieves events for a specific calendar within a given time range.

Endpoint: POST /api/v1/calendar/google/events

Request Body:

Note: The refreshToken field is currently required for testing purposes. In production, this will be omitted.

{
  "refreshToken": "1//0g...",
  "calendarId": "primary",
  "timeMin": "2024-01-01T00:00:00Z",
  "timeMax": "2024-01-31T23:59:59Z"
}

Parameters:

• calendarId (required): The ID of the calendar to fetch (use "primary" for the main calendar).
• timeMin (optional): Start of the time range (RFC3339 format).
• timeMax (optional): End of the time range (RFC3339 format).

Success Response: 200 OK

[
  {
    "calendarId": "primary",
    "title": "Weekly Standup",
    "description": "Zoom link in details",
    "location": "Virtual Office",
    "start": "2024-01-10T09:00:00+02:00",
    "startTimezone": "Europe/Rome",
    "end": "2024-01-10T09:30:00+02:00",
    "endTimezone": "Europe/Rome",
    "allDay": false,
    "visibility": "public",
    "recurrence": "RRULE:FREQ=WEEKLY;BYDAY=MO",
    "organizer": {
      "email": "manager@example.com",
      "name": "Manager Name"
    },
    "attendees": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "status": "accepted"
      }
    ]
  }
]

Disconnect Calendar (FUTURE)

Revokes the integration with the google calendar provider and deletes the stored tokens. This stops all background synchronization.

Endpoint: POST /api/v1/calendar/google/disconnect

Request Body: None

Success Response: 200 OK

---

Microsoft Integration (FUTURE)

Initiate Outlook Connection (FUTURE)

Generates a Microsoft OAuth authorization URL.

Endpoint: POST /api/v1/calendar/microsoft/connect

Request Body:

{
  "state": "random_string_xyz",
  "codeChallenge": "pkce_challenge_string"
}

Parameters:

• state (required): A random string generated by the client to prevent CSRF attacks.
• codeChallenge (required): The PKCE code challenge generated by the client.

Success Response: 200 OK

{
  "redirectUrl": "https://api.workos.com/oauth/authorize?..."
}

Disconnect Calendar (FUTURE)

Revokes the integration with the microsoft calendar provider and deletes the stored tokens. This stops all background synchronization.

Endpoint: POST /api/v1/calendar/microsoft/disconnect

Request Body: None

Success Response: 200 OK

---