Onboarding Embed

Embed Cal.com account creation, onboarding, and OAuth authorization directly in your app

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.

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.

After a new user signs up through the embed, Cal.com sends them a verification email to confirm their email address.

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

Prop	Type	Required	Description
oAuthClientId	string	Yes	Your OAuth client ID.
host	string	No	Cal.com host URL. Defaults to https://app.cal.com. Used for local development to point to the Cal web app.
theme	"light" | "dark"	No	Theme for the embedded onboarding UI. Defaults to "light".
user	{ email?: string, name?: string, username?: string }	No	Prefill user details in signup and profile steps.
authorization	AuthorizationProps	Yes	OAuth authorization parameters (see below).
onAuthorizationAllowed	(result: { code: string }) => void	No	Called with the authorization code on completion. If provided, enables callback mode. If omitted, enables redirect mode.
onError	(error: OnboardingError) => void	No	Called on unrecoverable error.
onAuthorizationDenied	() => void	No	Called when the user declines OAuth authorization. If omitted, the browser navigates to redirectUri?error=access_denied&state=YOUR_STATE.
onClose	() => void	No	Called when the user dismisses the dialog before completing.
trigger	ReactNode	No	Custom trigger element. Defaults to a “Continue with Cal.com” button.

Authorization props

Prop	Type	Required	Description
redirectUri	string	Yes	One of the redirect URIs registered on your OAuth client. Must share the same origin as the page hosting <OnboardingEmbed />, because the iframe uses postMessage for secure communication.
scope	string[]	Yes	OAuth scopes to request. Must be a subset of scopes registered on the OAuth client. See the OAuth scopes documentation.
state	string	Yes	CSRF token. Generate a unique value per session and verify it when you receive the authorization code.
codeChallenge	string	For public clients	PKCE code challenge (S256 method). Required for public OAuth clients.

If the user signs up via Google, the user prop values are ignored — name, email, and username are inferred from the Google account instead.

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:

Light theme (default)	Dark theme

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: "[e-mail]", 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;
}

Code	Description
INVALID_PROPS	Required props are missing or invalid (e.g. oAuthClientId does not exist, redirectUri does not match a registered URI, or required authorization fields are empty).
SIGNUP_FAILED	Account creation failed.
ONBOARDING_FAILED	An error occurred during the onboarding steps.
AUTHORIZATION_FAILED	The user denied access or OAuth consent failed.
STATE_MISMATCH	The state in the response did not match the state you provided. Possible CSRF attack.
UNKNOWN	An unexpected error occurred.

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.