Cal.com API Guide: v2 Docs, OAuth, Webhooks and Rate Limits

What the Cal.com API looks like in 2026

There is one Cal.com API now. It is version 2, a REST API that covers bookings, event types, schedules, slots, calendars, teams, organizations, routing forms, webhooks and more. The older API v1 is gone. Cal.com announced in August 2025 that v1 support would end, deprecated it on February 28, 2026, and shut it down on April 8, 2026, when all v1 endpoints were removed ^[1]. If a tutorial or a code sample you find still calls v1, it will not work against the hosted service, so treat it as history.

The move changed more than a version number. In v1 you passed your API key as a query parameter. In v2 the key travels as a Bearer token in the Authorization header, and most endpoints also expect a cal-api-version header that pins the shape of the request and response. That header matters more than it looks. Some endpoints fall back to an older version without it, and others, such as booking attendees, simply return a 404. Always send the version header, even when an example in the docs leaves it out.

Getting an API key and making your first call

API keys are the quickest way in, and they suit scripts, internal tools and server-to-server work. You create one in your account settings, give it a name and an expiry date, and copy it once. The docs disagree slightly on where the button lives: the agents guide points to Settings, Developer, API Keys, while the API introduction mentions the Security settings. Check both if you cannot find it. Keys carry a prefix that tells you the mode, cal_ for test and cal_live_ for live, which helps when you scan logs for a leaked secret.

What a key can and cannot do

A key acts as you, with everything your account can reach. An older 2024 post said there is no limit on the number of active keys, so create one per integration and retire it on its own schedule. You can also refresh a key through the API, which generates a new key and deletes the current one in a single call. Every request must use HTTPS. Plain HTTP calls fail, and so do unauthenticated requests to anything that is not a public endpoint. For a single company automating its own calendar, a key is usually all you need.

Running the API against a local instance

Developers who run the code locally hit an extra step. Cal.com's local setup guide says API v2 in a local instance needs a license key in CALCOM_LICENSE_KEY, and the docs publish a staging key for testing only. By default the web app runs on port 3000 and the API v2 server on port 3003. The community edition, Cal.diy, ships API v2 and API keys but no v1 at all, and it does not unlock team or organization features through the API. Our guide to Cal.com and open source covers that split.

OAuth for apps that other people connect

If you are building a product that other Cal.com users will connect to, you need OAuth instead of keys. You create an OAuth client in the developer settings of the web app, choose at least one scope and register up to 10 redirect URIs, which must match exactly. New clients start in a pending state and need approval from a Cal.com admin, who notifies you by email ^[2]. While a client is pending, only its owner can use it for testing. Changing the client's name, logo, website, redirect URIs or adding scopes sends it back to review, so settle those details before launch.

Tokens, scopes and secrets

Access tokens last 30 minutes, and you renew them with a refresh token that keeps the original scopes. Build the refresh path on day one. Scopes come in three levels: individual, TEAM_ and ORG_, and an ORG_ scope automatically grants the matching TEAM_ scope. Examples include reading event types, writing bookings, reading schedules and reading insights. Requests outside the granted scopes are rejected, and endpoints whose description names no scope cannot be called with an OAuth token at all. Public clients, such as single-page and mobile apps, use PKCE with S256 instead of a secret. Confidential clients can hold two active secrets at once, which allows rotation without downtime.

One legacy trap deserves a warning. Clients created before scopes existed issue tokens that can reach any resource of the authorizing user, because scopes are not enforced for them. If you still run one of those, recreate it with scopes. Do it before an audit finds it. To appear as an official partner app in the Cal.com App Store, you also need a verified OAuth client.

The endpoint groups you will actually use

The v2 reference is long, but most integrations touch a handful of groups. Start with those. Access to team and organization endpoints runs through three layers: a membership role, a permission in Cal.com's role-based access control, and, for OAuth tokens, a scope. Organization admins and owners can reach any team endpoint without being a member of that team. Everyone else needs the membership.

Bookings and slots

A single POST /v2/bookings endpoint creates regular, recurring and instant bookings. Other booking endpoints confirm, decline, reassign and update bookings, but reassignment works only for round robin bookings. Requesting a reschedule cancels the booking and emails the attendee a link to pick a new time. You can add guests to an existing booking, at most 10 per request and 30 in total, though not on seated events, and that endpoint is limited to 5 requests a minute. Changing a booking's location provisions a fresh Zoom, Google Meet or Cal Video link. Slots can be reserved through the API, by default for 5 minutes, while your own interface collects the booker's details. The time is held meanwhile.

Event types, schedules and calendars

Event type endpoints treat the team and parent IDs as fixed, so moving an event type to another team means deleting and recreating it. Calendar endpoints cover ICS feeds plus Google, Outlook and Apple credentials. Conferencing is narrower: through the API only Google Meet can be connected directly, and only alongside a Google Calendar connection, while Zoom and Microsoft Teams need an OAuth flow. Cal Video recordings, meeting sessions and transcript download links are available to the organizer and to team or org admins. User booking limits, which cap total bookings per day, week, month or year, are available only to organization members; others get a 403.

Routing, workflows, credits and the rest

Routing form endpoints include a slot calculation call that returns the routed event type and its slots without saving a response, plus a routing trace that shows how a booking was routed. Workflow endpoints exist, and API version 2026-09-22 adds conditional paths, but they are closed to third-party OAuth tokens. Credit endpoints check the balance of a user, team or org and charge credits, which matters for apps that send SMS or run AI agents. There are also Insights endpoints, an IP allowlist endpoint listing Cal.com's address ranges, notification subscriptions and Out of Office endpoints. Organizations get more on top: custom roles, attribute sync history and attendee blocking.

Public endpoints that need no authentication

Some of the most useful calls need no key at all. Creating, cancelling and rescheduling bookings and checking slot availability are public endpoints in API v2, and they need no OAuth scope either. Cal.com's agents guide makes the point directly: an AI agent can book on behalf of an outside user without credentials. That makes a custom booking front end cheap to build. You read available slots, show them in your own design, then create the booking with the attendee's details, all without storing a secret in the browser.

The trade-off is that the booking UID becomes your security boundary. Cal.com's FAQ describes the UID in API v2 as acting like a secret key. It is not guessable and not iterable, and you should never share it. Anyone holding a booking's UID can act on that booking through the public endpoints, so keep UIDs out of public URLs, analytics tools and client-side logs. Treat them the way you would treat a password reset link.

Rate limits and how to raise them

With an API key, the default limit is 120 requests per minute ^[3]. The API introduction says it can be raised to about 200 on request, and that higher limits, such as 800 a minute, may involve extra charges. The agents guide puts it more simply: contact support for more. Some endpoints carry their own tighter limits, like the 5-a-minute cap on adding guests. Cal.com's own comparison post notes that the default can be raised on request, so plan your batch jobs around 120 and ask early if you need more.

Limits also change after incidents. On January 27, 2026, a database load incident degraded the platform and caused full downtime for some enterprise customers. Cal.com's review traced part of the quota burn to retry logic in Atoms, and afterward DELETE endpoints were limited to 1 request per second. The lesson for integrators is plain. Back off on errors, and never retry in a tight loop.

Webhooks: triggers, security and payload versions

Webhooks push events to your server instead of making you poll. You can attach them at the user, event type, team or organization level, and Cal.com lists more than 20 triggers. They cover bookings created, cancelled, rescheduled, rejected, requested and paid, payment initiated, no-show updates, meetings started and ended, recordings ready, transcriptions generated, instant meetings and routing form submissions. Newer triggers include BOOKING_REASSIGNED, added in August 2026 for round robin and collective host changes, and a set of delegation credential triggers for organizations. If you would rather not write code, Cal.com points to Zapier as the no-code path.

HTTPS, signatures and the cloud rules

On the hosted service, subscriber URLs must use HTTPS, and private IPs and localhost are blocked, including hostnames that resolve to private addresses. An invalid URL is rejected with a 400 error. Self-hosted instances accept plain HTTP and private IPs, which is handy for testing but not for production. To verify that a payload came from Cal.com, set a secret on the webhook. Cal.com signs the body with HMAC SHA256 and sends the result in the X-Cal-Signature-256 header ^[4]. Compute the same hash on your side and compare before trusting anything in the payload. Skipping that check is risky.

Payload versions and quirks

Payloads are versioned through the x-cal-webhook-version header, a feature added in January 2026. Two versions exist: 2021-10-20 and 2026-07-27. The newer one adds ready-made calendar invite strings for the attendee and organizer, so your system can send its own emails. You can also shape payloads with a custom template, except for meeting started and ended events, which use a flat format. For seated events, each webhook carries only the attendee of the seat that triggered it. A routing form submission without a booking fires its trigger 15 minutes later. Managed event types are a weak spot: team-level webhooks skip them unless set on the parent or child event types.

Platform, Atoms, MCP and the CLI

The older Platform offering, with managed users and white labeling, stopped taking new sign-ups on December 15, 2025, and serves existing customers only. In January 2026 Cal.com moved from that white-label model to a branded Continue with Cal.com OAuth flow, and the Platform OAuth client, managed user and webhook endpoints are listed as deprecated. Atoms, the React components for booking, availability and calendar connection, are in maintenance mode: existing integrations get fixes and npm releases, but no new atoms are planned. Cal.com tells new integrations to start from API v2, and says the next generation will be copy-and-paste components.

For AI tools, Cal.com runs a hosted MCP server at mcp.cal.com that uses OAuth and needs no API key, so Claude, Cursor or VS Code can read bookings and manage event types in plain language. A local version runs through npx with your API key and needs Node.js 18 or later. Cal.com also recommends its CLI, the @calcom/cli package, for agents that can run commands, rather than calling the API directly. Our Cal.com AI guide covers the agent side in more depth.

Which plan you need for API access

Plan rules are the murkiest part of the API story. The pages disagree. Cal.com's August 2026 API comparison says API access is not available on the hosted Free plan and points free users to the self-hosted Cal.diy edition instead, while the same page says webhooks work from the free hosted plan. The pricing page lists custom APIs on Teams and additional APIs on Organizations. The API introduction is more specific: Teams customers get every endpoint except those prefixed Platform and Orgs. A 2024 post said all account types had API keys, which is older than all of this. Our reading is simple. Budget for Teams if the API matters to your project.

Organizations matters when you need organization-level controls. Custom roles, attribute sync history and per-user booking limits are organization features in the API, and Cal.com says SAML SSO and compliance capabilities are tied to Organizations at the API level too. Round robin through the API needs Teams, as it does in the app. If you only want a booking widget on your site, you may not need the API at all. Our Cal.com embed guide shows what embeds can do without code on your server.

The bottom line

The Cal.com API is now a single, reasonably complete REST API v2, after v1 shut down on April 8, 2026. API keys suit your own automations; OAuth suits apps others connect, at the cost of admin approval, 30-minute tokens and careful scope design. Public booking endpoints make custom front ends easy, and signed, versioned webhooks keep other systems in sync. Watch the 120-request default limit, the version header and the plan rules, and skip Platform and Atoms for new projects. For most teams, Teams is the plan where the API becomes dependable.