docs: api v2 rate limits (#24971)

docs/api-reference/v2/introduction.mdx

@@ -1,9 +1,10 @@
 ---
-title: 'Introduction to API v2'
-description: 'Introduction to Cal.com API v2 endpoints'
+title: "Introduction to API v2"
+description: "Introduction to Cal.com API v2 endpoints"
 ---
 
 ## Platform endpoints
+
 Platform customers have the following endpoints available:
 
 1. Endpoints prefixed with "Platform".
@@ -11,12 +12,26 @@ Platform customers have the following endpoints available:
 3. If you are at least on the ESSENTIALS plan, then all endpoints prefixed with "Orgs" except "Orgs / Attributes", "Orgs / Attributes / Options" and "Orgs / Teams / Routing forms / Responses".
 
 ## 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.
 
 ## Teams endpoints
+
 Teams customers have all the endpoints except the ones prefixed with "Platform" and "Orgs".
 
+## Rate limits
+
+There are three authentication methods for the API, and each of them has the following rate limits:
+
+1. API Key - 120 requests per minute. This can be increased to a reasonable amount, such as 200 requests per minute. If you require a higher rate limit, such as 800 requests per minute, it is possible, but it may involve extra charges. To request this, please contact support.
+
+2. Platform OAuth Client Credentials - 500 requests per minute
+
+3. Managed User Access Token - 500 requests per minute
+
+If no authentication method is provided, the default rate limit is 120 requests per minute.
+
 ## Authentication
 
 The Cal.com API has 3 authentication methods:
@@ -50,6 +65,7 @@ in your request header.
 All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
 
 ### 2. OAuth client credentials
+
 You need to use OAuth credentials when:
 
 1. Managing managed users [API reference](https://cal.com/docs/api-reference/v2/platform-managed-users/create-a-managed-user)
@@ -67,6 +83,7 @@ OAuth credentials can be accessed in the platform dashboard https://app.cal.com/
 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.
 
 You need to use access token when managing managed user's:
+
 1. Schedules [API reference](https://cal.com/docs/api-reference/v2/schedules/create-a-schedule)
 2. Event types [API reference](https://cal.com/docs/api-reference/v2/event-types/create-an-event-type)
 3. Bookings - some endpoints like creating a booking is public, but some like getting all managed user's bookings require managed user's access token [API reference](https://cal.com/docs/api-reference/v2/bookings/get-all-bookings)
@@ -76,4 +93,3 @@ It is passed as an authorization bearer request header Authorization: Bearer \<a
 Validity period: access tokens are valid for 60 minutes and refresh tokens for 1 year, and tokens can be refreshed using the refresh endpoint [API reference](https://cal.com/docs/api-reference/v2/oauth/post-v2oauth-refresh). After refreshing you will receive the new access and refresh tokens that you have to store in your database.
 
 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).
-