Calendar Service API Endpoints

The production API base URL is https://api.tradesmentechnologies.com/.

Authentication

Most endpoints require a Bearer token in the Authorization header: Authorization: Bearer <your_token>

Mutating requests may carry an Idempotency-Key header so a retry never acts twice — see Idempotent Retries in the Accounts API documentation.

The Calendar Webhook endpoint is public and does not require authentication.

Base Path

/prod/calendar

Endpoints

Connect Google Calendar

Exchange a Google OAuth server auth code for tokens and connect the employee's Google Calendar.

• Method: POST
• Path: /prod/calendar/connect
• Authentication: Required (Bearer Token)
• Request Body:

  {
    "serverAuthCode": "4/0AX4XfWh...",
    "redirectUri": "postmessage"
  }
  

  Note: serverAuthCode is required. This is the authorization code received from the Google OAuth consent flow. Note: redirectUri is optional. It must be sent (with the exact value "postmessage") when the auth code was obtained via the Google Identity Services popup flow in a browser (the web app); any other non-absent value is rejected with 400. When absent, the code is exchanged with an empty redirect URI, which matches codes from the native mobile sign-in flow.
• Success Response: 200 OK

  {
    "message": "Google Calendar connected",
    "googleEmail": "user@gmail.com"
  }
  

  Note: googleEmail is an empty string when Google's userinfo lookup fails (e.g. the grant carries no identity scope); the connection still succeeds.
• Error Responses:
  • 400 Bad Request: Missing request body, missing serverAuthCode, invalid redirectUri, no refresh token received from Google, or the user approved consent without granting the calendar permission (Google granular consent). In the last case the body carries "code": "CALENDAR_SCOPE_NOT_GRANTED" so clients can show a specific message, and the server revokes the unusable grant (best-effort) so a corrected retry receives a fresh refresh token.
  • 401 Unauthorized: Missing or invalid token.
  • 500 Internal Server Error: Unexpected server error.
• Side Effects: On success, triggers an asynchronous full calendar sync and sets up a watch channel for real-time updates.

Disconnect Google Calendar

Disconnect the employee's Google Calendar integration.

• Method: POST
• Path: /prod/calendar/disconnect
• Authentication: Required (Bearer Token)
• Request Body: None
• Success Response: 200 OK

  {
    "message": "Google Calendar disconnected"
  }
  

• Error Responses:
  • 401 Unauthorized: Missing or invalid token.
  • 404 Not Found: Google Calendar not connected for this employee.
  • 500 Internal Server Error: Unexpected server error.
• Side Effects: Stops the watch channel, revokes the Google OAuth token, and deletes all calendar event mappings for the employee.

Get Calendar Status

Check whether the authenticated employee has a connected Google Calendar.

• Method: GET
• Path: /prod/calendar/status
• Authentication: Required (Bearer Token)
• Success Response (Connected): 200 OK

  {
    "connected": true,
    "googleEmail": "user@gmail.com"
  }
  

• Success Response (Not Connected): 200 OK

  {
    "connected": false,
    "googleEmail": null
  }
  

• Error Responses:
  • 401 Unauthorized: Missing or invalid token.
  • 500 Internal Server Error: Unexpected server error.

Calendar Webhook

Receives push notifications from Google Calendar when events change. This is a public endpoint called by Google.

• Method: POST
• Path: /prod/calendar/webhook
• Authentication: None (public endpoint)
• Headers (from Google):
  • X-Goog-Channel-ID: The watch channel ID identifying the employee.
  • X-Goog-Resource-State: The event state (sync, exists, not_exists).
• Success Response: 200 OK
• Error Responses:
  • 400 Bad Request: Missing channel ID header.
• Note: Always returns 200 to acknowledge receipt, even on internal errors (webhook best practice). When X-Goog-Resource-State is sync, it acknowledges the verification ping without processing. For other states, it triggers an asynchronous inbound sync of calendar changes.