Skip to main content
The Cal.com Platform API supports two authentication methods: API keys for server-to-server communication and OAuth 2.0 for third-party applications.

​
Authentication Methods

API Keys

Simple authentication for server-to-server integrations

OAuth 2.0

Secure authentication for third-party applications

​
API Key Authentication

API keys are the simplest way to authenticate with the Platform API. They’re ideal for:
  • Server-to-server integrations
  • Internal tools and scripts
  • Testing and development

​
Creating an API Key

  1. Log in to your Cal.com account
  2. Navigate to Settings > Security > API Keys
  3. Click Create New API Key
  4. Give your key a descriptive name
  5. Copy the key immediately (it won’t be shown again)

​
Using API Keys

Include your API key in the Authorization header as a Bearer token: 
curl -X GET https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer cal_live_xxxxxxxxxxxxxxxx"
API keys start with cal_live_ for production and cal_test_ for development environments.

​
API Key Formats

cal_live_xxxxxxxxxxxxxxxx  # Production key
cal_test_xxxxxxxxxxxxxxxx  # Test/development key

​
Example Request with API Key

curl -X POST https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer cal_live_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 123,
    "start": "2024-03-15T10:00:00Z",
    "responses": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }'

​
Refreshing API Keys

You can refresh an API key to generate a new one and invalidate the old one: 
POST /v2/api-keys/refresh
Request: 
curl -X POST https://api.cal.com/v2/api-keys/refresh \
  -H "Authorization: Bearer cal_live_old_key" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresAt": "2025-12-31T23:59:59Z"
  }'
Response: 
{
  "status": "success",
  "data": {
    "apiKey": "cal_live_new_xxxxxxxxxxxxxxxx"
  }
}
The old API key will be immediately invalidated. Update all systems using the old key before refreshing.

​
OAuth 2.0 Authentication

OAuth 2.0 is recommended for third-party applications that need to access Cal.com data on behalf of users. It provides:
  • Secure delegated access
  • User authorization
  • Token-based authentication
  • Scope-based permissions
See the OAuth 2.0 Guide for detailed implementation instructions.

​
OAuth Flow Overview

1

Register OAuth Client

Create an OAuth client in your Cal.com settings
2

Redirect User to Authorization

Send users to the authorization endpoint
3

Receive Authorization Code

User authorizes and you receive a code
4

Exchange Code for Tokens

Exchange the authorization code for access and refresh tokens
5

Make API Requests

Use the access token to make authenticated requests

​
Using Access Tokens

Access tokens are used the same way as API keys: 
curl -X GET https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer <access_token>"

​
Authentication Guard Types

The Platform API uses different authentication guards for different endpoints:

​
ApiAuthGuard

Requires valid authentication (API key or OAuth token): 
@UseGuards(ApiAuthGuard)
@Get('/bookings')
async getBookings(@GetUser() user: UserWithProfile) {
  // User is authenticated
}

​
OptionalApiAuthGuard

Authentication is optional but will extract user info if provided: 
@UseGuards(OptionalApiAuthGuard)
@Get('/public-data')
async getPublicData(@GetOptionalUser() user?: AuthOptionalUser) {
  // User may or may not be authenticated
}

​
Authentication Methods Comparison

FeatureAPI KeysOAuth 2.0
Use CaseServer-to-serverThird-party apps
Setup ComplexitySimpleModerate
User AuthorizationNot requiredRequired
Token ExpirationOptionalAutomatic
Scope-based PermissionsNoYes
Best ForInternal integrationsPublic applications

​
Security Best Practices

  • Never commit API keys to version control
  • Use environment variables or secure vaults
  • Rotate keys regularly
  • Use different keys for different environments
  • Always use HTTPS for API requests
  • Never send credentials over unencrypted connections
  • Verify SSL certificates
  • Refresh OAuth tokens before they expire
  • Handle token expiration gracefully
  • Store refresh tokens securely
  • Request only the scopes you need
  • Use read-only scopes when possible
  • Review permissions regularly

​
Error Handling

​
401 Unauthorized

Returned when authentication credentials are missing or invalid: 
{
  "status": "error",
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}
Common causes:
  • Missing Authorization header
  • Invalid API key format
  • Expired access token
  • Revoked credentials

​
403 Forbidden

Returned when the authenticated user lacks permissions: 
{
  "status": "error",
  "error": {
    "message": "Insufficient permissions",
    "code": "FORBIDDEN"
  }
}
Common causes:
  • Insufficient OAuth scopes
  • Attempting to access another user’s resources
  • Organization/team permission restrictions

​
Testing Authentication

Test your authentication setup with a simple request: 
curl -X GET https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -v
Successful authentication returns a 200 status code and your bookings data.

​
Rate Limits by Authentication Type

Authentication MethodDefault LimitTime Window
API Key120 requests60 seconds
OAuth Client500 requests60 seconds
Access Token500 requests60 seconds
Unauthenticated (IP)120 requests60 seconds
See Rate Limits for more details.

​
Migration from v1 to v2

If you’re migrating from API v1:
  • API keys remain the same
  • Base URL changes from /api/v1 to /v2
  • Add cal-api-version header for version control
  • OAuth 2.0 implementation is new in v2

​
Next Steps

OAuth 2.0 Guide

Learn how to implement OAuth 2.0

Rate Limits

Understand rate limiting policies

Webhooks

Set up webhook authentication

API Reference

Browse all available endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us