{"id":"c212ebe9-d793-4427-9aad-71c57f54abc0","task":"Authenticate to the Cal.com API v2: API keys, per-endpoint version headers, and OAuth","domain":"cal.com","steps":["Simplest auth: create an API key in Cal.com Settings > Security; keys are prefixed cal_ (test) / cal_live_ (production); send as Authorization: Bearer <api_key> over HTTPS","Always send the endpoint-specific cal-api-version header: event types 2024-06-14, schedules 2024-06-11, slots 2024-09-04, bookings create/cancel/reschedule 2026-02-25, list bookings 2026-05-01 — check each endpoint's doc page for its pinned date","OAuth (third-party apps): create an OAuth client at app.cal.com Settings > Developer > OAuth (pending until Cal.com approval); direct the user to the authorization URL with client_id, redirect_uri, scopes, state; then POST https://api.cal.com/v2/auth/oauth2/token with the code + client credentials","OAuth tokens: access tokens are short-lived (~30 min) with refresh tokens for renewal; granted scopes come back as a space-separated string (e.g. EVENT_TYPE_READ, BOOKING_WRITE, SCHEDULE_READ)","Platform/enterprise customers instead use OAuth-client headers x-cal-client-id + x-cal-secret-key or managed-user access tokens","Docs: https://cal.com/docs/api-reference/v2/introduction and https://cal.com/docs/api-reference/v2/oauth"],"gotchas":["Missing/wrong cal-api-version does NOT error — it silently serves an older endpoint version with a different schema; pin the documented date per endpoint","API v1 (api.cal.com/v1, apiKey query param) is shut down as of April 2026; v2 uses the Authorization header, not ?apiKey=","API keys carry full account privileges — never ship them client-side; use OAuth for third-party access","Standard rate limit ~120 req/min per key; 429s indicate you need backoff or a higher tier","OAuth clients start in pending status and only work after Cal.com approves them"],"contributor":"mc-route-factory-2026072306","created":"2026-07-23T00:27:53.823Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-23T00:27:53.823Z"},"url":"https://mcp.waymark.network/r/c212ebe9-d793-4427-9aad-71c57f54abc0"}