CTRL K
Skip to Content
🚀 Getting Startedoauth-setup

Last Updated: 6/9/2026

OAuth Setup & Connecting Zoom

Connect your Zoom account to ZCal Buddy to sync your calendar events to the home screen widget. The app uses OAuth 2.0 authentication with an external redirect to securely access your Zoom calendar.

Prerequisites

  • Android device running Android 8.0 (API 26) or higher
  • Active Zoom account with calendar access
  • ZCal Buddy app installed
  • Web browser on your device

Understanding the OAuth Flow

ZCal Buddy uses a two-step redirect process to authenticate with Zoom:

  1. Browser Authorization: The app opens your browser to Zoom’s authorization page at https://zoom.us/oauth/authorize with client ID lzTeqRJYQx29JbipyhcAYA and redirect URI https://trevanbusby.com/redirect.

  2. External Redirect: After you approve access, Zoom redirects to the trevanbusby.com endpoint with an authorization code. This HTTPS redirect is required because Zoom OAuth doesn’t support direct custom URI schemes for this app type.

  3. Return to App: The trevanbusby.com page immediately hands the authorization code back to the app via the custom URI zcalbuddy://oauth, which the app’s manifest listens for.

  4. Token Exchange: The app sends the authorization code to https://www.trevanbusby.com/_functions/zoomToken, which exchanges it for access and refresh tokens. This serverless function keeps the client secret secure.

You’ll see the browser redirect briefly—this is normal and expected behavior.

Connecting Your Zoom Account

Step 1: Start OAuth Flow

Open ZCal Buddy and tap Connect Zoom on the home screen. The app calls ZoomConfig.buildAuthorizationIntent() to construct the authorization URL with these parameters:

"https://zoom.us/oauth/authorize" +
    "?response_type=code" +
    "&client_id=lzTeqRJYQx29JbipyhcAYA" +
    "&redirect_uri=https://trevanbusby.com/redirect"

Your default browser opens to Zoom’s authorization page.

Step 2: Authorize Calendar Access

Log in to your Zoom account if prompted. Review the permissions ZCal Buddy is requesting:

  • Read your calendar events
  • Create and modify calendar events
  • Create Zoom meetings
  • Access your calendar list

These permissions allow the app to display events in the widget, let you RSVP to invitations, create new events with Zoom meetings, and edit existing events.

Tap Authorize to grant access.

Step 3: Complete the Redirect

Zoom redirects to https://trevanbusby.com/redirect with an authorization code in the URL. The page automatically redirects to zcalbuddy://oauth?code=<authorization_code>, which opens ZCal Buddy.

The app’s MainActivity captures the code via intent.data?.getQueryParameter("code") and stores it in oauthCodeState. A LaunchedEffect observes this state change and triggers the token exchange:

LaunchedEffect(oauthCode) {
    if (!oauthCode.isNullOrBlank()) {
        status.value = "Connecting to Zoom..."
        val result = withContext(Dispatchers.IO) {
            syncService.connectAndSync(context, oauthCode)
        }
        // ... handle result
    }
}

Step 4: Verify Connection

The app calls ZoomAuthRepository.exchangeCodeForToken(code) to exchange the authorization code for tokens. The function posts to the token exchange URL:

val json = """
    {
      "code": "$code",
      "redirectUri": "https://trevanbusby.com/redirect"
    }
""".trimIndent()

If successful, the app stores the access token and refresh token using TokenRepository, fetches your calendar list and events, and displays “Calendar synced.” The widget automatically updates with your events.

You should see your calendar events appear in the app and on the home screen widget within a few seconds.

What Happens After Connection

Once connected, ZCal Buddy:

  • Stores your access token and refresh token encrypted with Android Keystore using AES/GCM
  • Fetches your calendar list from https://api.zoom.us/v2/calendars/users/me/calendarList
  • Retrieves events from each calendar via https://api.zoom.us/v2/calendars/{calendarId}/events
  • Saves events and calendar metadata locally using DataStore
  • Schedules automatic widget refresh every 15 minutes via WorkManager

The refresh token allows the app to obtain new access tokens when they expire, so you don’t need to re-authenticate unless you disconnect or revoke access from Zoom’s settings.

Troubleshooting Connection Issues

“We couldn’t finish the Zoom connection. Try again.”

This message appears when the token exchange fails. Common causes:

  • Network connectivity issues during the OAuth flow
  • Authorization code expired (codes are single-use and time-limited)
  • Server-side token exchange function unavailable

Solution: Tap Connect Zoom again to restart the OAuth flow. The app will generate a new authorization request.

Browser doesn’t redirect back to app

If you’re stuck on the trevanbusby.com redirect page:

  1. Manually open ZCal Buddy from your app drawer
  2. The app will show “Connect Zoom to sync your calendar”
  3. Tap Connect Zoom to try again

“No saved Zoom access token. Connect Zoom again.”

This appears when the app can’t find stored tokens. This happens if:

  • You haven’t completed the OAuth flow yet
  • You disconnected Zoom from the app settings
  • App data was cleared

Solution: Tap Connect Zoom to authenticate again.

Token Refresh

Access tokens expire after a period determined by Zoom. When the app detects an expired token, it automatically calls ZoomAuthRepository.refreshAccessToken(refreshToken) to obtain a new access token:

val json = """
    {
      "refreshToken": "$refreshToken"
    }
""".trimIndent()

This posts to https://www.trevanbusby.com/_functions/zoomRefresh, which handles the refresh with Zoom’s API and returns a new access token. The app stores the new token and continues the operation that triggered the refresh.

Token refresh happens transparently—you won’t see any prompts or interruptions. If the refresh token itself expires or is revoked, you’ll need to reconnect by completing the OAuth flow again.

Permissions and Privacy

ZCal Buddy requests these OAuth scopes from Zoom:

  • calendar:read - View your calendar events
  • calendar:write - Create and modify events
  • meeting:write - Create Zoom meetings for events

The app stores tokens encrypted using Android Keystore with AES/GCM mode. Calendar data is stored locally in encrypted DataStore preferences. No calendar data is sent to external servers except Zoom’s API endpoints.

You can revoke access anytime from Zoom’s account settings under Connected Apps, or disconnect from ZCal Buddy’s settings screen.

What’s Next

Now that your Zoom account is connected, install the widget on your home screen to see your calendar events. See Installing the Widget for step-by-step instructions on adding the widget and choosing your preferred view mode.

installing-widgetoverview