diff --git a/docs/api-reference/v2/introduction.mdx b/docs/api-reference/v2/introduction.mdx index f78ce33c4f..3d6f06c289 100644 --- a/docs/api-reference/v2/introduction.mdx +++ b/docs/api-reference/v2/introduction.mdx @@ -7,24 +7,29 @@ description: "Introduction to Cal.com API v2 endpoints" The Cal.com API has 3 authentication methods: -1. OAuth +1. OAuth (Recommended) 2. API key +3. Platform (Deprecated) -### 1. Create an OAuth client and "Continue with Cal.com" +### 1. OAuth [Recommended] In order to be listed as an official partner and App in our App Store: cal.com/apps you need to create and get a verified OAuth client. -You can request it here: https://cal.com/docs/oauth. + + **Create an OAuth client and "Continue with Cal.com"** + + +You can request it here: https://cal.com/docs/api-reference/v2/oauth. ### 2. API key -While API keys can be created easily, bear in mind we almost always recommend using OAuth credentials, especially when building integrations or applications with Cal.com. +While API keys can be created easily, bear in mind we almost always recommend using OAuth credentials, especially when building integrations or applications with Cal.com. You can view and manage your API keys in your settings page under the security tab in Cal.com. - +![](/images/i1600x899-DllqhV6w_3Vj_oxtjov.png) -API Keys are under Settings > Security +API Keys are under Settings \> Security Test mode secret keys have the prefix `cal_` and live mode secret keys have the prefix `cal_live_`. @@ -46,8 +51,7 @@ Teams customers have all the endpoints except the ones prefixed with "Platform" ## Organizations endpoints -Organizations customers have all the endpoints except the ones prefixed with "Platform" and "Teams" and "Orgs / Orgs" because -children organizations are only allowed in the platform plan right now. +Organizations customers have all the endpoints except the ones prefixed with "Platform" and "Teams" and "Orgs / Orgs" because children organizations are only allowed in the platform plan right now. ## Rate limits @@ -57,12 +61,11 @@ There are three authentication methods for the API, and each of them has the fol If no authentication method is provided, the default rate limit is 120 requests per minute. - ## Deprecated & Maintenance for existing users only As of 15th December 2025, we're currently undergoing a restructuring of our "Platform"-offering. Until further we continue to provide enterprise support for existing customers but no longer offer new signups for any "Platform" plan. -### 2. Platform OAuth client credentials +### 1. Platform OAuth client credentials [Deprecated] You need to use OAuth credentials when: @@ -76,7 +79,7 @@ OAuth credentials can be accessed in the platform dashboard https://app.cal.com/ 1. `x-cal-client-id` - ID of the OAuth client. 2. `x-cal-secret-key` - secret of the OAuth client. -### 3. Platform Managed user access token +### 2. Platform Managed user access token [Deprecated] After you create a managed user you will receive its access and refresh tokens. The response also includes managed user's id, so we recommend you to add new properties to your users table calAccessToken, calRefreshToken and calManagedUserId to store this information. @@ -92,8 +95,7 @@ Validity period: access tokens are valid for 60 minutes and refresh tokens for 1 Recovering tokens: if you ever lose managed user's access or refresh tokens, you can force refresh them using the OAuth client credentials and store them in your database [API reference](https://cal.com/docs/api-reference/v2/platform-managed-users/force-refresh-tokens). - -## Platform endpoints +### Platform endpoints [Deprecated] Platform customers have the following endpoints available: diff --git a/docs/oauth.mdx b/docs/api-reference/v2/oauth.mdx similarity index 97% rename from docs/oauth.mdx rename to docs/api-reference/v2/oauth.mdx index 29d71026cc..2e974056a7 100644 --- a/docs/oauth.mdx +++ b/docs/api-reference/v2/oauth.mdx @@ -1,5 +1,6 @@ --- -title: "How to use OAuth to authorize apps with cal.com accounts" +title: "OAuth" +description: "Authorize apps with cal.com accounts using OAuth" --- As an example, you can view our OAuth flow in action on Zapier. Try to connect your cal.com account [here](https://zapier.com/apps/calcom/integrations). To enable OAuth in one of your apps, you will need a Client ID, Client Secret, Authorization URL, Access Token Request URL, and Refresh Token Request URL. diff --git a/docs/mint.json b/docs/mint.json index a1a98fb8eb..ac7f8edfe3 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -32,6 +32,11 @@ "url": "https://app.cal.com" }, "tabs": [ + { + "name": "API v2 Reference", + "openapi": "/api-reference/v2/openapi.json", + "url": "api-reference/v2" + }, { "name": "Developing", "url": "developing" @@ -41,25 +46,24 @@ "url": "self-hosting" }, { - "name": "OAuth", - "url": "oauth" - }, - { - "name": "API v2 Reference", - "openapi": "/api-reference/v2/openapi.json", - "url": "api-reference/v2" - }, - { - "name": "API v1 Reference", + "name": "API v1 Reference [Deprecated]", "openapi": "/api-reference/v1/openapi-v1.json", "url": "api-reference/v1", "banner": { "type": "warning", - "content": "API v1 will be discontinued on February 15, 2026. Please migrate to [API v2](/api-reference/v2/introduction)." + "content": "API v1 is deprecated and will be discontinued on February 15, 2026. Please migrate to [API v2](/api-reference/v2/introduction)." } } ], "navigation": [ + { + "group": "Getting Started", + "pages": [ + "api-reference/v2/introduction", + "api-reference/v2/oauth", + "api-reference/v2/v1-v2-differences" + ] + }, { "group": "Getting Started", "pages": ["developing/introduction", "developing/local-development"] @@ -204,64 +208,6 @@ } ] }, - { - "group": "Getting Started", - "pages": [ - "platform/introduction", - "platform/setup", - "platform/quickstart", - { - "group": "Atoms", - "icon": "atom", - "pages": [ - "platform/atoms/apple-calendar-connect", - "platform/atoms/availability-settings", - "platform/atoms/booker", - "platform/atoms/booker-embed", - "platform/atoms/cal-provider", - "platform/atoms/calendar-settings", - "platform/atoms/calendar-view", - "platform/atoms/conferencing-apps", - "platform/atoms/create-schedule", - "platform/atoms/event-type", - "platform/atoms/google-calendar-connect", - "platform/atoms/list-event-types", - "platform/atoms/list-schedules", - "platform/atoms/outlook-calendar-connect", - "platform/atoms/payment-form", - "platform/atoms/stripe-connect" - ] - }, - { - "group": "Hooks", - "icon": "brackets-curly", - "pages": [ - "platform/bookings-hooks", - "platform/event-types-hooks", - "platform/calendars-hooks", - "platform/user-or-team-related-hooks" - ] - }, - { - "group": "Guides", - "icon": "book", - "pages": [ - "platform/guides/replacing-toasts", - "platform/guides/booking-fields", - "platform/guides/booking-redirects", - "platform/guides/managed-orgs", - "platform/guides/teams-setup", - "platform/guides/global-event-types", - "platform/guides/custom-booking-flow" - ] - }, - "platform/faq" - ] - }, - { - "group": "Getting Started", - "pages": ["api-reference/v2/introduction", "api-reference/v2/v1-v2-differences"] - }, { "group": "Getting Started", "pages": [ diff --git a/docs/platform/guides/global-event-types.mdx b/docs/platform/guides/global-event-types.mdx index e4bf6e64d7..afd654384c 100644 --- a/docs/platform/guides/global-event-types.mdx +++ b/docs/platform/guides/global-event-types.mdx @@ -1,8 +1,12 @@ --- -title: Global event types +title: Global event types [Deprecated] description: Event types that every managed user or a subset of managed users will have automatically --- + +This is now deprecated and under Maintenance for existing users only + + If you want all of your managed users or a subset of managed users to have the same event type set up automatically, then follow along. ## Prerequisites diff --git a/docs/platform/introduction.mdx b/docs/platform/introduction.mdx index f5a5ea6176..d98952afd8 100644 --- a/docs/platform/introduction.mdx +++ b/docs/platform/introduction.mdx @@ -5,10 +5,6 @@ icon: "presentation-screen" - - Get started - - Customizable UI components handling scheduling on behalf of your users diff --git a/docs/platform/quickstart.mdx b/docs/platform/quickstart.mdx index c7bf49aa02..7e396df3b4 100644 --- a/docs/platform/quickstart.mdx +++ b/docs/platform/quickstart.mdx @@ -4,10 +4,7 @@ description: Find out how to use Cal "atoms" to integrate scheduling into your p "icon": "rocket" --- -## 1. Unlocking access to atoms -1. Sign up for a Platform account [here](https://app.cal.com/signup?redirect=https://app.cal.com/settings/platform/new) - -## 2. Setting up an OAuth client +## 1. Setting up an OAuth client Once your account is created, the next step is to create an OAuth client. This allows you to connect your users to Cal and handle their scheduling with atoms. @@ -23,7 +20,7 @@ Once your account is created, the next step is to create an OAuth client. This a 4. Profile: When you proceed to the chapter 2, you will create your users on our end, so that we can manage their scheduling. Profile permissions allow to either read or update users you create on our end. 5. Apps: used to connect Google Calendar, Zoom, Microsoft Teams, etc. to atoms. -## 3. Creating managed users connected to the OAuth client +## 2. Creating managed users connected to the OAuth client In order for atoms to handle scheduling on behalf of your users, you have to create what we call a “managed user” for each of your users. @@ -93,7 +90,7 @@ Second, if `timeZone` is passed in the request, the user's default schedule from if the `timeZone` is not passed, then user has no default schedule and user can't be booked and user can't set availability using the `AvailabilitySettings` atom. You will have to set it up manually via the `/schedules` endpoints. We recommend setting the `timeZone` for ease of use. -## 4. Backend: setting up a refresh token endpoint +## 3. Backend: setting up a refresh token endpoint You have to set up an endpoint on your server to which atoms can send an expired access token and receive new one in return. This exchange will be automatically handled by atoms when you provide this endpoint URL when setting up frontend in the next step. @@ -122,7 +119,7 @@ Shortly: The atoms will now use the new access token to handle scheduling on behalf of your user. Access token expires after 60 minutes and atoms then will make a request to your refresh token endpoint to get a new access token while also refreshing the refresh token. -## 5. Managing refresh token expiry +## 4. Managing refresh token expiry Each refresh token is valid for 1 year. When a managed user's access token is refreshed, the refresh token is refreshed too. However, to make sure that refresh tokens do not expire for less active users you have 2 options: @@ -132,11 +129,11 @@ is about to expire, then refresh tokens using the [`/refresh`](https://cal.com/d refresh token has expired, call the [`/force-refresh`](https://cal.com/docs/api-reference/v2/platform-managed-users/force-refresh-tokens) endpoint - it allows you to refresh managed user tokens using only the OAuth client ID and client secret and is intended to be used in cases when one of the tokens is lost or the refresh token is expired. -## 6. Frontend: setting up atoms +## 5. Frontend: setting up atoms Atoms are customizable UI components handling scheduling on behalf of your users. -### 6.1 Install the atoms package +### 5.1 Install the atoms package npm: @@ -156,7 +153,7 @@ pnpm: pnpm add @calcom/atoms ``` -### 6.2 Set up environment variables +### 5.2 Set up environment variables CAL_OAUTH_CLIENT_ID: OAuth client ID @@ -241,7 +238,7 @@ function MyApp({ Component, pageProps }) { export default MyApp; ``` -## 7. Frontend: using atoms +## 6. Frontend: using atoms It’s very easy, just import the atom and drop it in code! For example, for users to connect their Google Calendar drop in "Connect.GoogleCalendar" component - it will handle everything. @@ -288,7 +285,7 @@ other more complex atoms will expose multiple classNames and props to react to e />; ``` -## 8. Front-end: passing additional props to CalProvider +## 7. Front-end: passing additional props to CalProvider The CalProvider component offers several additional props to customize its behavior and appearance: 1. autoUpdateTimezone: By default, the atoms automatically update the user's timezone. You can disable this feature by setting autoUpdateTimezone to false. diff --git a/docs/platform/setup.mdx b/docs/platform/setup.mdx deleted file mode 100644 index de129aff05..0000000000 --- a/docs/platform/setup.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Setup -icon: "user-shield" -description: Get started with creating a platform account ---- - - - - - Head over to the [Cal.com](https://cal.com/) landing page and create a new account by clicking on the **Get Started** button at the top right corner. - - - This will redirect you to the Cal.com signup page which looks like this - - - - - After you sign up and create your account, go the [platform setup page](https://app.cal.com/settings/platform/new) where you are prompted to set up your platform team. - - - - - Once your platform team is created, you'll need to subscribe via stripe for the plan that you want to choose. - - - - - Once you subscribe via stripe, you will be redirected back to the platform setup page where you'll be able to see your platform dashboard. You're ready to start building with platform, head over to Quickstart for further steps. - - - -