Authentication

Authenticate with the Cal.com Platform API using API keys or OAuth 2.0

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

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": "[e-mail]"
    }
  }'

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

Feature	API Keys	OAuth 2.0
Use Case	Server-to-server	Third-party apps
Setup Complexity	Simple	Moderate
User Authorization	Not required	Required
Token Expiration	Optional	Automatic
Scope-based Permissions	No	Yes
Best For	Internal integrations	Public applications

Security Best Practices

Store Credentials Securely

• Never commit API keys to version control
• Use environment variables or secure vaults
• Rotate keys regularly
• Use different keys for different environments

Use HTTPS Only

• Always use HTTPS for API requests
• Never send credentials over unencrypted connections
• Verify SSL certificates

Implement Token Refresh

• Refresh OAuth tokens before they expire
• Handle token expiration gracefully
• Store refresh tokens securely

Limit Scope and Permissions

• 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 Method	Default Limit	Time Window
API Key	120 requests	60 seconds
OAuth Client	500 requests	60 seconds
Access Token	500 requests	60 seconds
Unauthenticated (IP)	120 requests	60 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