Onboarding Embed

Archived Cal.com Atoms documentation for Onboarding Embed. These deprecated SDK components are no longer maintained.

The OnboardingEmbed atom lets you embed the full Cal.com signup, onboarding, and OAuth authorization flow directly inside your application. Users create a Cal.com account, complete onboarding, and grant your app OAuth access — all without leaving your site.

For a demonstration of the onboarding embed flow, please refer to the video below.

Watch the video

When to use this

Use the Onboarding Embed when you want new users to connect their Cal.com account during your app's own signup or setup flow. Instead of redirecting users to Cal.com and back, the entire process happens in an embedded dialog.

Prerequisites

  • An OAuth client created via OAuth setup
  • The @calcom/atoms package installed in your project

Modes

The component supports two modes for receiving the authorization code:

  • Callback mode — provide onAuthorizationAllowed to receive the authorization code via a callback. No page navigation occurs.
  • Redirect mode — omit onAuthorizationAllowed and the browser navigates to your redirectUri with the code as a query parameter.

Callback mode

Provide onAuthorizationAllowed to receive the authorization code directly. The dialog closes and your callback fires after the user authorizes your OAuth client — no page reload.

import { OnboardingEmbed } from "@calcom/atoms";
import { useState } from "react";

function App() {
  const [state] = useState(() => crypto.randomUUID());

  return (
    <OnboardingEmbed
      oAuthClientId="your_client_id"
      authorization={{
        scope: ["BOOKING_READ", "BOOKING_WRITE", "PROFILE_READ"],
        redirectUri: "https://your-app.com/cal/callback",
        state,
      }}
      onAuthorizationAllowed={({ code }) => {
        fetch("/api/cal/exchange", {
          method: "POST",
          body: JSON.stringify({ code, state }),
        });
      }}
      onError={(error) => console.error(error.code, error.message)}
      onClose={() => console.log("Dialog dismissed")}
    />
  );
}

Redirect mode

Omit onAuthorizationAllowed and the browser navigates to your redirectUri after the user completes onboarding and grants access:

https://your-app.com/cal/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE
import { OnboardingEmbed } from "@calcom/atoms";
import { useState } from "react";

function App() {
  const [state] = useState(() => crypto.randomUUID());

  return (
    <OnboardingEmbed
      oAuthClientId="your_client_id"
      authorization={{
        scope: ["BOOKING_READ", "BOOKING_WRITE", "PROFILE_READ"],
        redirectUri: "https://your-app.com/cal/callback",
        state,
      }}
      onError={(error) => console.error(error.code, error.message)}
    />
  );
}

Props

Authorization props

Trigger and theme

The theme prop controls the appearance of the trigger button, the onboarding steps, and the authorization page. The default trigger renders a "Continue with Cal.com" button:

You can pass a custom trigger element via the trigger prop:

<OnboardingEmbed
  trigger={<button>Connect calendar</button>}
  // ...other props
/>

User flow walkthrough

Here's what happens when a user clicks the trigger with onAuthorizationAllowed provided and the user prop set:

<OnboardingEmbed
  oAuthClientId="your_client_id"
  theme="light"
  user={{ email: "bob@yahoo.com", name: "Bob", username: "bob100" }}
  authorization={{
    scope: ["EVENT_TYPE_READ"],
    redirectUri: "https://your-app.com/cal/callback",
    state,
  }}
  onAuthorizationAllowed={({ code }) => {
    alert(`Success! Auth code: ${code}`);
  }}
/>

1. Trigger — The component renders a "Continue with Cal.com" button. The user clicks it to open the onboarding dialog.

2. Login or signup — The dialog opens with the login form. Existing users can sign in with email or Google. The user.email prop prefills the email field.

New users click "Create account" to sign up with Google or email. When signing up with email, the user.email and user.username props are prefilled.

3. Profile — After signup, the user sets up their profile. The user.name prop prefills the name field.

4. Connect calendar — The user can connect a calendar or skip this step.

5. Authorize — The user reviews the requested permissions and clicks "Allow". The displayed permissions correspond to the scope passed to the component.

6. Done — onAuthorizationAllowed fires with the authorization code. Exchange it for tokens using the token endpoint.

Public clients (PKCE)

Public OAuth clients cannot safely store a client secret (e.g. browser-only apps). Use PKCE to secure the authorization code exchange instead. Generate a code_verifier, derive a code_challenge from it, and pass the challenge to OnboardingEmbed. When you receive the authorization code, exchange it with the code_verifier instead of a client secret.

import { OnboardingEmbed } from "@calcom/atoms";
import { useEffect, useMemo, useState } from "react";

async function generatePkce() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  const codeVerifier = btoa(String.fromCharCode(...array))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");

  const digest = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(codeVerifier)
  );
  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");

  return { codeVerifier, codeChallenge };
}

export function MyApp() {
  const state = useMemo(() => crypto.randomUUID(), []);
  const [pkce, setPkce] = useState<{
    codeVerifier: string;
    codeChallenge: string;
  } | null>(null);

  useEffect(() => {
    generatePkce().then(setPkce);
  }, []);

  if (!pkce) return null;

  return (
    <OnboardingEmbed
      oAuthClientId="your_client_id"
      authorization={{
        scope: ["EVENT_TYPE_READ"],
        redirectUri: "https://your-app.com/cal/callback",
        state,
        codeChallenge: pkce.codeChallenge,
      }}
      onAuthorizationAllowed={async ({ code }) => {
        const res = await fetch("https://api.cal.com/v2/auth/oauth2/token", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            client_id: "your_client_id",
            code_verifier: pkce.codeVerifier,
            grant_type: "authorization_code",
            code,
            redirect_uri: "https://your-app.com/cal/callback",
          }),
        });
        const { access_token, refresh_token } = await res.json();
      }}
    />
  );
}

Error handling

The onError callback receives an error object with the following shape:

interface OnboardingError {
  code:
    | "INVALID_PROPS"
    | "SIGNUP_FAILED"
    | "ONBOARDING_FAILED"
    | "AUTHORIZATION_FAILED"
    | "STATE_MISMATCH"
    | "UNKNOWN";
  message: string;
}

How it works

The component opens a dialog containing an iframe that loads Cal.com's onboarding flow. The iframe runs on Cal.com's domain with a first-party session, so no third-party cookies are needed.

The flow automatically detects the user's state:

  • No session — starts at signup/login, then profile setup, calendar connection, and OAuth consent.
  • Session with incomplete onboarding — resumes from where the user left off.
  • Session with complete onboarding — skips straight to OAuth consent.

After the user grants access, you receive an authorization code that you exchange for access and refresh tokens using the token endpoint.

Last updated