Credential Sync Example App

Purpose and Scope

The credential-sync example is a small Next.js application that demonstrates an external credential authority for Cal.diy app integrations. In this model, the example app is the source of truth for app credentials: it can generate an access token itself and then synchronize that token into the Cal.diy app. That makes it useful when you want to understand how a separate service could manage integration credentials instead of relying only on credentials created inside the main Cal.diy web application.

Sources: example-apps/credential-sync/README.md, example-apps/credential-sync/pages/index.tsx

This page covers the structure and runtime behavior visible in the example application. It explains how to start the app, which query parameters select the managed credential target, how the UI triggers synchronization, and which environment variable connects Cal.diy back to the credential-sync service. The example is intentionally narrow: it is not a full app-store integration guide, but a playground for exercising the credential handoff between a local Next.js service and a Cal.diy instance.

The example sits under example-apps/credential-sync, which marks it as an example application rather than a reusable package. Its package manifest identifies it as private and names it @calcom/example-app-credential-sync, so it is intended to run from the monorepo workspace rather than be published as an external npm package. The dependencies include Next.js, React, Prisma, and @calcom/atoms, showing that the example follows the same platform-oriented stack used elsewhere in the repository while remaining self-contained for local experimentation.

Sources: example-apps/credential-sync/package.json

Relevant Source Files

• example-apps/credential-sync/README.md - Defines the example app's purpose, local development command, management URL, and the credential-sync endpoint that Cal.diy must call.
• example-apps/credential-sync/package.json - Declares the workspace package name, scripts, runtime dependencies, and development dependencies used to run and build the example app.
• example-apps/credential-sync/pages/index.tsx - Implements the browser playground for choosing a user and app slug, then sending valid or invalid credentials to Cal.diy through an API route.

Core Primitives

The core primitive in this example is the managed credential target. The UI models that target with two URL query parameters: userId and appSlug. userId identifies the Cal.diy user whose credential should be managed, while appSlug identifies the app integration being tested. If those query parameters are missing, the page redirects to a default target using userId=1 and appSlug=google-calendar, which gives the playground a concrete starting point without requiring the developer to type a query string on first load.

Sources: example-apps/credential-sync/pages/index.tsx

The second primitive is the credential sync endpoint. The README states that http://localhost:5100/api/getToken should be configured as the value of CALCOM_CREDENTIAL_SYNC_ENDPOINT in Cal.diy. That environment variable is the bridge from the main Cal.diy instance to the example service. When Cal.diy needs credentials from the external authority, it can call the configured endpoint rather than assuming the token was created or stored only inside Cal.diy itself.

Sources: example-apps/credential-sync/README.md

The third primitive is the token update action exposed by the playground UI. The landing page renders two buttons: one sends an invalid token to Cal.diy, and the other sends a valid token. Both buttons call the same updateToken function, which performs a GET request to /api/setTokenInCalCom with the selected userId, selected appSlug, and an invalid flag. This makes the playground useful for testing both happy-path synchronization and failure handling in a connected Cal.diy instance.

Sources: example-apps/credential-sync/pages/index.tsx

Development Workflow

Start the example with the dev script from its package. The script sets PORT=5100 and runs next dev, matching the README instruction that yarn dev starts the server on port 5100. After the server is running, open http://localhost:5100 to use the credential management playground. The manifest also includes build and start scripts for the conventional Next.js production build and start lifecycle, but the README describes the local development flow as the primary way to use the example.

Sources: example-apps/credential-sync/README.md, example-apps/credential-sync/package.json

cd example-apps/credential-sync
yarn dev
# open http://localhost:5100

To connect the example to a Cal.diy installation, configure the main application with the credential sync endpoint described by the README. For a local run, the endpoint is the example app's getToken route on port 5100. The exact environment file depends on the Cal.diy service you are running, but the value itself is explicit in the example documentation. Once configured, the main Cal.diy instance knows where to request externally managed credentials.

Sources: example-apps/credential-sync/README.md

CALCOM_CREDENTIAL_SYNC_ENDPOINT=http://localhost:5100/api/getToken

Execution Flow

When the browser loads the playground page, the component reads the current URL using Next.js navigation hooks. It extracts appSlug and userId from the search parameters, then runs an effect that normalizes the URL. If userId is missing, the effect adds userId=1; if appSlug is missing, it adds appSlug=google-calendar. When either default is added, the router pushes the updated URL, so subsequent actions always have both values available.

Sources: example-apps/credential-sync/pages/index.tsx

After the URL is normalized, the rendered page tells the operator exactly what credential target is being managed. The text includes the current userId and appSlug, and it explicitly says that changing query parameters manages a different user or app. This is an important detail for local testing because no separate selector UI is required: developers can switch test cases by editing the query string, reloading the page, or linking directly to a specific user-and-app combination.

Sources: example-apps/credential-sync/pages/index.tsx

The update action is deliberately simple. The updateToken function defaults to a valid-token mode, but accepts an object with invalid: true for the negative test. It sends a GET request to /api/setTokenInCalCom, passes invalid as 1 or 0, and includes the selected user and app slug. The response is parsed as JSON and displayed on the page, giving immediate feedback from the API route that attempted to write or sync the credential into Cal.diy.

Sources: example-apps/credential-sync/pages/index.tsx

API Contract Visible from the Example

The README and page code expose two local routes that matter to readers. The first is /api/getToken, which is the endpoint Cal.diy should call through CALCOM_CREDENTIAL_SYNC_ENDPOINT. The second is /api/setTokenInCalCom, which the playground calls to push a valid or invalid credential into Cal.diy for the selected target. The route bodies are outside the requested source set, so the stable contract to rely on here is the route naming, query-string shape, and the README-provided environment variable.

Sources: example-apps/credential-sync/README.md, example-apps/credential-sync/pages/index.tsx

Implementation Details and Next Steps

Use the example as a controlled playground rather than as production credential infrastructure. It is designed to show the shape of an external token authority: select a Cal.diy user, select an app slug, generate or choose the token state, and invoke synchronization. Because it can intentionally send an invalid token, it is also useful for verifying how a Cal.diy instance responds when app credentials become stale, revoked, or malformed.

Sources: example-apps/credential-sync/README.md, example-apps/credential-sync/pages/index.tsx

A practical next step is to run the example next to a local Cal.diy instance, set CALCOM_CREDENTIAL_SYNC_ENDPOINT, and start with the default google-calendar app slug. Then repeat the flow with another app slug that exists in your installation. Watch both browser output and server logs while clicking the valid and invalid token buttons. That gives you a fast feedback loop for validating credential sync behavior before adapting the pattern for a real integration service.