docs: Clean up (#26879)
* clean-up nav * Documentation edits made through Mintlify web editor * Documentation edits made through Mintlify web editor * further clean up * add oauth in sidebar * -- * land in v2 * land in v2 * Documentation edits made through Mintlify web editor * Documentation edits made through Mintlify web editor * cleanup * Documentation edits made through Mintlify web editor * deprecated v1 --------- Co-authored-by: Syed Ali Shahbaz <alishahbaz7@gmail.com> Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
This commit is contained in:
mintlify[bot]
co-authored by
Syed Ali Shahbaz
mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Syed Ali Shahbaz
mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
parent
9ea71d2ba5
commit
c5213be60d
@@ -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.
|
||||
<Note>
|
||||
**Create an OAuth client and "Continue with Cal.com"**
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
<img src="/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:
|
||||
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
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.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
### Get your OAuth "Continue with [Cal.com](http://Cal.com)" Badge
|
||||
|
||||
- https://app.cal.com/continue-with-calcom-coss-ui.svg
|
||||
- https://app.cal.com/continue-with-calcom-dark-rounded.svg
|
||||
- https://app.cal.com/continue-with-calcom-dark-squared.svg
|
||||
- https://app.cal.com/continue-with-calcom-light-rounded.svg
|
||||
- https://app.cal.com/continue-with-calcom-light-squared.svg
|
||||
- https://app.cal.com/continue-with-calcom-neutral-rounded.svg
|
||||
- https://app.cal.com/continue-with-calcom-light-squared.svg
|
||||
|
||||
|
||||
### OAuth Client Credentials
|
||||
|
||||
Only the cal.com team can create new OAuth clients. Please fill out [this form](https://i.cal.com/forms/4052adda-bc79-4a8d-9f63-5bc3bead4cd3) and book us to get started.
|
||||
|
||||
The Cal.com team will register the app and provide you with the Client ID and Client Secret. Keep these credentials confidential and secure.
|
||||
|
||||
### Authorization URL
|
||||
|
||||
To initiate the OAuth flow, direct users to the following authorization URL:
|
||||
|
||||
- `https://app.cal.com/auth/oauth2/authorize`
|
||||
- URL Parameters:
|
||||
- _client_id_
|
||||
- _state_: A securely generated random string to mitigate CSRF attacks
|
||||
- _redirect_uri_: This is where users will be redirected after authorization
|
||||
|
||||
After users click _Allow_, they will be redirected to the redirect_uri with the code (authorization code) and state as URL parameters.
|
||||
|
||||
### Access Token Request
|
||||
|
||||
Endpoint: `POST https://app.cal.com/api/auth/oauth/token`
|
||||
|
||||
Request Body:
|
||||
|
||||
- _code_: The authorization code received in the redirect URI
|
||||
- _client_id_
|
||||
- _client_secret_
|
||||
- _grant_type_: "authorization_code"
|
||||
- _redirect_uri_
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
access_token: “exampleAccessToken”
|
||||
refresh_token: “exampleRefreshToken”
|
||||
}
|
||||
```
|
||||
|
||||
### Refresh Token Request
|
||||
|
||||
Endpoint: `POST https://app.cal.com/api/auth/oauth/refreshToken`
|
||||
|
||||
Headers:
|
||||
|
||||
- Authorization: Bearer _exampleRefreshToken_
|
||||
|
||||
Request Body:
|
||||
|
||||
- _grant_type_: "refresh_token"
|
||||
- _client_id_
|
||||
- _client_secret_
|
||||
|
||||
Response:
|
||||
|
||||
```
|
||||
{
|
||||
access_token: “exampleAccessToken”,
|
||||
refresh_token: "exampleRefreshToken"
|
||||
}
|
||||
```
|
||||
|
||||
### Testing OAuth Credentials
|
||||
|
||||
To verify the correct setup and functionality of OAuth credentials you can use the following endpoint: `GET https://api.cal.com/v2/me`
|
||||
|
||||
Headers:
|
||||
|
||||
- Authorization: Bearer _exampleAccessToken_
|
||||
Reference in New Issue
Block a user