Files
cal.diy/agents/skills/calcom-api/references/authentication.md
T
Benny JooandDevin AI ab21c7f805 refactor: Cal.diy (#28903)
* feat: Cal.diy — community-driven MIT-licensed fork of Cal.com

This squashed commit contains all Cal.diy changes applied on top of calcom/cal.com main:

- Rebrand Cal.com to Cal.diy across the entire codebase
- Remove Enterprise Edition (EE) features, license checks, and AGPL restrictions
- Switch license from AGPL-3.0 to MIT
- Remove docs/ directory (migrated to Nextra at cal.diy)
- Remove dead code: org tests, EE tips, platform nav, premium username, SAML/SSO, etc.
- Clean up .env.example for self-hosted Cal.diy
- Update Docker image references to calcom/cal.diy
- Update README, CONTRIBUTING.md, and issue templates for Cal.diy community fork
- Add PR welcome bot for Cal.diy contributors
- Fix API v2 breaking changes oasdiff ignore entries
- Replace Blacksmith CI runners with default GitHub Actions

3893 files changed, 20789 insertions(+), 411020 deletions(-)

Co-Authored-By: [email protected] <[email protected]>

* refactor: remove org-specific /organizations/:orgId endpoints from API v2 atoms controllers (#1701)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix: revert Cal.diy Inc to Cal.com, Inc. in license files, copyright notices, and package metadata (#1702)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* rip out org related comments in api v2

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-04-15 09:52:36 -03:00

407 lines
9.0 KiB
Markdown

# Authentication API Reference
Detailed documentation for authentication methods in the Cal.diy API v2.
## Authentication Methods
Cal.diy API v2 supports two authentication methods:
1. **API Key Authentication** - For direct API access
2. **OAuth/Platform Authentication** - For platform integrations managing users on behalf of others
## API Key Authentication
The primary authentication method for most API consumers.
### Obtaining an API Key
1. Log in to your Cal.diy account
2. Navigate to Settings > Developer > API Keys
3. Click "Create new API key"
4. Copy and securely store the generated key
### Using API Keys
Include the API key in the `Authorization` header with the `Bearer` prefix:
```http
GET /v2/bookings
Authorization: Bearer cal_live_abc123xyz...
```
### API Key Format
All Cal.diy API keys are prefixed with `cal_`:
- `cal_live_...` - Production API keys
- `cal_test_...` - Test/sandbox API keys (if available)
### Example Request
```bash
curl -X GET "https://api.cal.com/v2/bookings" \
-H "Authorization: Bearer cal_live_abc123xyz789" \
-H "Content-Type: application/json"
```
## Refresh API Key
Generate a new API key and invalidate the current one:
```http
POST /v2/api-keys/refresh
Authorization: Bearer cal_live_current_key
Content-Type: application/json
{
"expiresAt": "2025-12-31T23:59:59Z"
}
```
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| expiresAt | string | No | ISO 8601 expiration date for the new key |
### Response
```json
{
"status": "success",
"data": {
"apiKey": "cal_live_new_key_xyz..."
}
}
```
## Platform Authentication (OAuth)
For platform customers building integrations that manage multiple users.
### Headers for Platform Authentication
Platform customers use additional headers alongside or instead of the Bearer token:
| Header | Description |
|--------|-------------|
| `x-cal-client-id` | OAuth client ID |
| `x-cal-secret-key` | OAuth client secret key |
| `Authorization` | Bearer token (managed user access token) |
### Example Platform Request
```bash
curl -X GET "https://api.cal.com/v2/bookings" \
-H "x-cal-client-id: your_client_id" \
-H "x-cal-secret-key: your_secret_key" \
-H "Authorization: Bearer managed_user_access_token" \
-H "Content-Type: application/json"
```
### When to Use Each Header
**For endpoints acting on behalf of a managed user:**
```http
GET /v2/bookings
x-cal-client-id: your_client_id
x-cal-secret-key: your_secret_key
Authorization: Bearer managed_user_access_token
```
**For platform-level operations (managing OAuth clients):**
```http
GET /v2/oauth-clients
Authorization: Bearer cal_live_platform_admin_key
```
## API Versioning
Many endpoints require a version header:
```http
cal-api-version: 2024-08-13
```
### Example with Version Header
```bash
curl -X POST "https://api.cal.com/v2/bookings" \
-H "Authorization: Bearer cal_live_abc123" \
-H "cal-api-version: 2024-08-13" \
-H "Content-Type: application/json" \
-d '{"start": "2024-01-15T10:00:00Z", "eventTypeId": 123, ...}'
```
## Authentication Errors
### 401 Unauthorized
Returned when authentication fails:
```json
{
"status": "error",
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}
```
Common causes:
- Missing `Authorization` header
- Invalid or expired API key
- API key without `cal_` prefix
- Incorrect Bearer token format
### 403 Forbidden
Returned when authenticated but lacking permissions:
```json
{
"status": "error",
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to access this resource"
}
}
```
Common causes:
- Accessing another user's resources
- Missing required scopes for platform tokens
- Organization/team permission restrictions
## Security Best Practices
1. **Never expose API keys in client-side code**: API keys should only be used in server-side applications
2. **Use environment variables**: Store API keys in environment variables, not in code
```bash
export CAL_API_KEY="cal_live_abc123..."
```
3. **Rotate keys regularly**: Use the refresh endpoint to rotate keys periodically
4. **Use minimal permissions**: Request only the scopes/permissions your application needs
5. **Monitor API usage**: Check your Cal.diy dashboard for unusual activity
6. **Secure transmission**: Always use HTTPS for API requests
7. **Handle keys securely in logs**: Never log full API keys - redact sensitive portions
## Rate Limiting
API requests are rate limited. When exceeded, you'll receive:
```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```
```json
{
"status": "error",
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Please retry after 60 seconds."
}
}
```
### Rate Limit Headers
| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per window |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
| `Retry-After` | Seconds to wait before retrying (on 429) |
## Testing Authentication
Verify your API key is working:
```bash
curl -X GET "https://api.cal.com/v2/me" \
-H "Authorization: Bearer cal_live_your_api_key" \
-H "Content-Type: application/json"
```
### Expected Response
```json
{
"status": "success",
"data": {
"id": 12345,
"email": "[email protected]",
"username": "johndoe",
"name": "John Doe",
"timeZone": "America/New_York"
}
}
```
## Common Authentication Patterns
### Server-Side Integration
```javascript
const CAL_API_KEY = process.env.CAL_API_KEY;
async function getBookings() {
const response = await fetch('https://api.cal.com/v2/bookings', {
headers: {
'Authorization': `Bearer ${CAL_API_KEY}`,
'Content-Type': 'application/json',
'cal-api-version': '2024-08-13'
}
});
if (!response.ok) {
if (response.status === 401) {
throw new Error('Invalid API key');
}
throw new Error(`API error: ${response.status}`);
}
return response.json();
}
```
### Handling Token Refresh
```javascript
async function makeAuthenticatedRequest(url, options = {}) {
let response = await fetch(url, {
...options,
headers: {
...options.headers,
'Authorization': `Bearer ${apiKey}`
}
});
if (response.status === 401) {
// Refresh the API key
const refreshResponse = await fetch('https://api.cal.com/v2/api-keys/refresh', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({})
});
if (refreshResponse.ok) {
const { data } = await refreshResponse.json();
apiKey = data.apiKey;
// Retry original request with new key
response = await fetch(url, {
...options,
headers: {
...options.headers,
'Authorization': `Bearer ${apiKey}`
}
});
}
}
return response;
}
```
## Error Handling
The API returns standard HTTP status codes:
| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request (invalid parameters) |
| 401 | Unauthorized (invalid or missing API key) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 422 | Unprocessable Entity (validation error) |
| 429 | Too Many Requests (rate limited) |
| 500 | Internal Server Error |
### Error Response Format
```json
{
"status": "error",
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message"
}
}
```
### Common Error Codes
| Code | Description |
|------|-------------|
| UNAUTHORIZED | Invalid or missing authentication |
| FORBIDDEN | Insufficient permissions |
| NOT_FOUND | Resource not found |
| VALIDATION_ERROR | Invalid request parameters |
| RATE_LIMITED | Too many requests |
## Pagination
List endpoints support pagination via `take` and `skip` parameters:
| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| take | number | 10 | 250 | Number of items to return |
| skip | number | 0 | - | Number of items to skip |
### Example
```http
GET /v2/bookings?take=20&skip=40
```
This returns items 41-60 (skipping the first 40, taking 20).
### Pagination Response
Some endpoints include pagination metadata:
```json
{
"status": "success",
"data": [...],
"pagination": {
"total": 150,
"take": 20,
"skip": 40
}
}
```
## Troubleshooting
### "Invalid API key" Error
1. Verify the key starts with `cal_`
2. Check for extra whitespace or characters
3. Ensure the key hasn't been revoked or expired
4. Confirm you're using the correct environment (production vs test)
### "Missing Authorization header" Error
1. Ensure the header name is exactly `Authorization`
2. Include the `Bearer ` prefix (with space)
3. Check for typos in the header name
### Platform Authentication Issues
1. Verify both `x-cal-client-id` and `x-cal-secret-key` are provided
2. Ensure the managed user access token is valid
3. Check that the OAuth client has the required permissions